npm package: @lanonasis/memory-lanonasis
Description: Secret-safe memory plugin for OpenClaw — protects credentials and sensitive data from logs and memory storage, with semantic search and cross-channel persistence
Latest version: 0.3.5

# @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

```bash
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](https://github.com/thefixer3x/lan-onasis-monorepo/tree/main/packages/openclaw-plugin) if you want to verify.

For local development:

```bash
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:

```bash
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:

```json
{
  "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

```json
"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](#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:**

```bash
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:

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

## CLI

```bash
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:

```bash
# 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](./setup/agents-memory.md).

## Verification

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

For local in-house validation before publishing:

```bash
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:

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

## Publish

```bash
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](./SETUP.md) for operator setup details
- [CHANGELOG.md](./CHANGELOG.md) for release history