@lanonasis/memory-lanonasis

@lanonasis/memory-lanonasis

LanOnasis cloud memory plugin for OpenClaw.

It adds:

• openclaw lanonasis CLI commands for memory CRUD, search, list, stats, and extraction
• always-available agent tools: memory_search, memory_get, memory_store, memory_forget
• LanOnasis-backed semantic memory with cross-session persistence and OpenClaw slot integration
• cross-agent recall: personal → shared → deduplicate fallback chain
• extraction from JSONL session logs, Markdown docs, and SQLite memory databases
• embedding profile contract: stamp and detect provider/model mismatches

Install

openclaw plugins install @lanonasis/memory-lanonasis --dangerously-force-unsafe-install

Expected install warning: OpenClaw's static scanner flags any plugin that reads environment variables and makes network requests. You will see:

WARNING: Environment variable access combined with network send — possible credential harvesting

This is a false positive. The plugin reads LANONASIS_API_KEY from your environment and contacts api.lanonasis.com. That is the plugin's entire purpose. No credentials are sent anywhere except the LanOnasis API you configured. Source is on GitHub if you want to verify.

For local development:

cd packages/openclaw-plugin
npm install
npm run build
openclaw plugins install "$(pwd)" --link --dangerously-force-unsafe-install

Configuration

Set credentials in your environment before starting OpenClaw. ~/.openclaw/.env works, and dotenvx-managed env injection works too:

LANONASIS_API_KEY=your_key
LANONASIS_PROJECT_ID=your_project_id
LANONASIS_BASE_URL=https://api.lanonasis.com

Then reference those env vars from ~/.openclaw/openclaw.json instead of pasting literal secrets:

{
  "plugins": {
    "allow": ["memory-lanonasis"],
    "slots": {
      "memory": "memory-lanonasis"
    },
    "entries": {
      "memory-lanonasis": {
        "enabled": true,
        "config": {
          "apiKey": "${LANONASIS_API_KEY}",
          "projectId": "${LANONASIS_PROJECT_ID}",
          "agentId": "main",
          "captureMode": "hybrid",
          "autoRecall": true,
          "localFallback": true,
          "searchThreshold": 0.75,
          "dedupeThreshold": 0.985,
          "maxRecallResults": 5,
          "memoryMode": "hybrid",
          "sharedNamespace": "org-shared",
          "syncMode": "realtime",
          "embeddingProvider": "openai",
          "embeddingModel": "text-embedding-3-small",
          "embeddingProfileId": "prod-v1"
        }
      }
    }
  }
}

Key config fields:

• apiKey: required — prefer ${LANONASIS_API_KEY} over a literal secret in config
• projectId: required — prefer ${LANONASIS_PROJECT_ID} or an env-backed value
• baseUrl: defaults to https://api.lanonasis.com
• searchThreshold: recall similarity threshold (default: 0.75)
• dedupeThreshold: duplicate detection threshold for memory_store (default: 0.985)
• maxRecallResults: max memories injected during recall (default: 5)
• recallMode: auto | ondemand — controls whether recall is injected automatically (default: auto)
• maxRecallChars: hard cap on total injected recall characters (default: 1500)
• memoryMode: remote | local | hybrid (default: hybrid)
• sharedNamespace: cross-agent shared memory namespace (empty = disabled)
• syncMode: realtime | batch | manual (default: realtime)
• embeddingProvider: embedding provider name (for profile stamping)
• embeddingModel: embedding model name (for profile stamping)
• embeddingProfileId: stamped into metadata for mismatch detection

Context Window Management

Auto-recall injects up to maxRecallResults memories before each session. With the defaults (maxRecallResults: 5, searchThreshold: 0.75), this can add several hundred to ~1500 characters of context. For most large-context models this is negligible, but for Ollama and small-context models it can crowd out the working prompt.

Recommended config for Ollama / small-context models

"recallMode": "ondemand",
"maxRecallChars": 500,
"searchThreshold": 0.80,
"maxRecallResults": 3

Setting recallMode: "ondemand" disables automatic injection entirely — memory tools remain available, but recall only happens when you (or the agent) explicitly calls memory_search. Add a session-start instruction to your AGENTS.md to call memory_search manually (see Wiring Agent Guidance below).

The maxRecallChars cap provides a safety net even in auto mode: injection stops once the accumulated block would exceed the limit, regardless of maxRecallResults.

searchThreshold: 0.80 is recommended over the default 0.75 to reduce weakly-matched noise entries.

Wiring Agent Guidance

After install, the plugin registers its tools and wires up the recall slot — but your workspace AGENTS.md won't mention the memory tools unless you add it. This matters because OpenClaw's agent picks up tool declarations from AGENTS.md before starting a session.

One-liner to append the memory snippet to your workspace AGENTS.md:

cat "$(openclaw plugins path memory-lanonasis)/setup/agents-memory.md" >> ~/.openclaw/workspace/AGENTS.md

Or manually paste the contents of setup/agents-memory.md from this package into your AGENTS.md.

For on-demand mode, add this instruction at the top of the pasted block:

> **Session start:** Call `memory_search` with a short query about the current task before doing anything else.

Re-install vs update: openclaw plugins update does not update path-installed or npm-installed plugins in place. To upgrade, re-run the install command:

openclaw plugins install @lanonasis/memory-lanonasis@latest --dangerously-force-unsafe-install

CLI

openclaw lanonasis status
openclaw lanonasis create --title "Test" --content "Hello world"
openclaw lanonasis get <id-or-prefix>
openclaw lanonasis update <id-or-prefix> --title "Updated"
openclaw lanonasis delete <id-or-prefix> --force
openclaw lanonasis search "hello" --threshold 0.7 --type knowledge --tags alpha,beta
openclaw lanonasis list --page 1 --sort created_at --order desc
openclaw lanonasis stats

The CLI accepts full UUIDs or unambiguous 8+ character prefixes for get, update, and delete.

Extraction

The extractor supports multiple source formats with automatic detection:

JSONL formats (auto-detected on first line):

• openclaw-session — nested { type: "message", message: { role, content[] } } session logs
• openclaw-cache — cache-trace records with request/response payloads
• claude-code — flat { role, content } session logs
• codex — { type: "message", sender } format
• generic — fallback for any JSON with text fields

Document formats (auto-detected by file extension):

• markdown — .md / .mdx files, splits by heading sections
• sqlite — .sqlite / .db files, reads the OpenClaw chunks table

Examples:

# JSONL session logs
openclaw lanonasis extract ~/.openclaw/agents/main/sessions/sample.jsonl --dry-run

# Markdown agent docs
openclaw lanonasis extract ~/.openclaw/workspace/SOUL.md --dry-run

# SQLite memory databases (per-agent)
openclaw lanonasis extract ~/.openclaw/memory/main.sqlite --dry-run
openclaw lanonasis extract ~/.openclaw/memory/worker.sqlite --dry-run

# Force a specific format
openclaw lanonasis extract session.jsonl --format openclaw-session --dry-run

All extractors share the same pipeline: secret redaction → capture filter → prompt injection check → type detection → tag extraction → vector dedup → store.

API Behavior

The plugin targets the canonical REST surface first:

• /api/v1/memories
• /api/v1/memories/{id}
• /api/v1/memories/search
• /api/v1/memories/stats

Compatibility aliases on the same REST plane are still used when the canonical route returns 404 or 405, but the plugin no longer relies on hidden MCP rerouting to rescue API-base clients.

Agent Tools

The plugin registers:

• memory_search
• memory_get
• memory_store
• memory_forget

If you use explicit tool allowlists, allow either the plugin id memory-lanonasis or those tool names directly.

For workspace prompting guidance, see setup/agents-memory.md.

Verification

npm run typecheck
npm run test
npm run build
npm run pack:dry-run

For local in-house validation before publishing:

cd packages/openclaw-plugin
npm run build
openclaw plugins install "$(pwd)" --link --dangerously-force-unsafe-install
openclaw lanonasis extract /root/.openclaw/agents/main/sessions/sample.jsonl --format openclaw-session --dry-run

Integration checks against a live LanOnasis backend can be run from an installed extension copy with:

set -a
source ~/.openclaw/.env
node ~/.openclaw/extensions/memory-lanonasis/test-Integration.js

Publish

npm run verify:release
npm publish --access public
git tag memory-lanonasis-v$(node -p "require('./package.json').version")
git push origin main --follow-tags

prepublishOnly enforces typecheck and unit tests before publish. prepack rebuilds dist/. Pushing a memory-lanonasis-v<version> tag triggers the GitHub release workflow, which verifies the package, confirms the npm version exists, and attaches the generated .tgz to the release.

For local testing, you do not need to publish to npm first. A local build plus openclaw plugins install "$(pwd)" --link --force is enough to pick up the new plugin code on the machine you are testing.

More Docs

• SETUP.md for operator setup details
• CHANGELOG.md for release history