v0.3.1 — opt-in memory sidecar (stop the <mem> leak)

0.3.1 — Opt-in memory sidecar (stop the <mem> leak)

Patch release on top of 0.3.0. One behavior change, no migrations.

Fixed

• The ## Memory Sidecar prompt block is now opt-in (sidecar.enabled,
  default false). That block asks the agent to append a <mem>{...}</mem>
  line at the end of every turn. On backends whose reply delivery bypasses
  OpenClaw's message_sending hook — notably the claude-cli backend — the
  block is not stripped and leaked verbatim into user-facing replies
  (Telegram/Discord), with no way to remove it downstream. Until now it was
  emitted unconditionally on every install. It is now gated behind the
  (previously inert) sidecar.enabled flag and defaults OFF, so no deployment
  leaks <mem> out of the box.

  Memory capture is unaffected when the sidecar is off: memory_store and the
  transcript watcher still ingest every turn — the sidecar was only the
  cheapest of several capture paths. Re-enable it with
  sidecar: { enabled: true } in your memory-postgres plugin config once
  you've confirmed your backend strips the block before the user sees it. The
  flag is read once at plugin register time, so a openclaw gateway restart
  picks up a change.

• Bumped package-lock.json to match (0.3.0 shipped with a stale 0.2.1
  version stamp in the lockfile).

---

Install (curl-installed OpenClaw):

openclaw plugins install git:github.com/NextAgentBC/nextclaw@v0.3.1

v0.3.0 — Curated recall + action-sensitive memory

Memory-quality release on top of 0.2.1. Migrations 60/61/62 apply automatically on gateway restart.

New

• memory_get(chunkId) — fetch a chunk in full when a search snippet was truncated. Read-only; fail-closed per-agent isolation (another agent's chunk reads as not-found).
• Cited recall — memory_search surfaces inline pg://<source>/<chunkId> citations so the agent can attribute a claim and re-fetch via memory_get.
• Action-sensitive commitments — directives the agent might act on (cancel / send / authorize / appointments / reminders) are extracted into structured.commitments (agent-isolated) with safe_to_act / requires_confirmation / authority / validity, and flagged ⚠ on recall. Conservative by default: side-effecting directives require confirmation; only reminders are safe to act on.

Fixed

• Ingest dedup no longer pollutes last_recalled_at — the cold-tier aging signal was being bumped on every re-ingest, so chunks never aged into the cold tier. De-polluted 422/500 live chunks.
• Tuning analyzer no longer accumulates duplicate pending proposals (partial unique index + ON CONFLICT; collapsed 23 → 2 live).

Hygiene

• Declared memory_get in contracts.tools; removed the vestigial contracts.memoryEmbeddingProviders declaration (nextclaw self-embeds — it's an embedding consumer, not a host provider).

Verification

tsc clean · 146 unit tests · live transactional migration dry-runs · deployed and openclaw plugins inspect clean.

Full details: CHANGELOG.md · merged via #21.

v0.2.1 — Curl-first install + distribution fixes

0.2.1 — Curl-first install + distribution fixes

0.2.1 is a packaging / install-UX release. No new runtime features — the focus
is letting a non-developer install the plugin against a curl-installed OpenClaw
in under 10 minutes, on a machine with neither pnpm nor a source checkout.

Distributable via openclaw plugins install git: / npm:

• package.json openclaw.extensions now points at ./dist/index.js. The
  previous ./index.ts value only worked for local-development checkouts —
  OpenClaw's plugin installer requires a compiled entry for any non---link
  install source. Verified live: openclaw plugins install git:github.com/NextAgentBC/nextclaw against a curl-installed OpenClaw now
  succeeds end-to-end, registers memory-postgres as an enabled plugin, and
  surfaces the dashboard at 127.0.0.1:8765 after openclaw gateway restart.
• dist/ (752 KB, 75 files) is now tracked in git. OpenClaw's installer runs
  npm install --omit=dev --omit=peer, which strips the typescript compiler,
  so any prepare-time rebuild is impossible during a normal install. The
  in-tree dist is the source of truth. Contributors must npm run build and
  git add dist/ before merging source changes — a comment at the top of
  .gitignore calls this out.
• New scripts/prepare-build.mjs. Invoked from the prepare script. When
  typescript is resolvable (regular dev checkouts) it rebuilds; otherwise it
  cleanly skips and prints a one-line note. Either way the install succeeds
  with a usable dist/.
• openclaw.plugin.json had two "activation" keys at the top of the
  manifest. The second one shadowed the first, forcing onStartup: false.
  Now deduped → plugin activates on gateway startup as intended.

Documentation rewritten around curl-installed OpenClaw

• README.md Quick Start replaced. Old flow was clone OpenClaw → pnpm install && pnpm build → drop nextclaw into extensions/ → pnpm openclaw gateway start. New flow is:

  curl -fsSL https://openclaw.ai/install.sh | bash
  openclaw onboard --install-daemon
  # ... pick Postgres (Neon or Docker)
  openclaw plugins install git:github.com/NextAgentBC/nextclaw
  curl -fsSL .../scripts/configure-minimal.mjs | PG_URL=... node --input-type=module
  openclaw gateway restart

• Postgres step now offers Neon (zero local deps, free tier) as Option A
  alongside a single-docker run Option B. Neither requires cloning this repo
  to get a docker-compose.yml.
• New helper scripts/configure-minimal.mjs. Pipes through curl | node. Reads
  the existing ~/.openclaw/openclaw.json (created by openclaw onboard),
  injects only plugins.slots.memory and plugins.entries["memory-postgres"],
  writes back. Round-trip tested against a real onboard-produced config: every
  non-plugins key (gateway, agents, auth, channels, …) is byte-identical
  before/after. Masks the Postgres password in its stdout output.
• New "Other install methods" section in README enumerates git / npm /
  ClawHub / local-dev install sources. Notes that the bare nextclaw npm
  name is taken by an unrelated CLI, so any future npm publish will be
  scoped (e.g. @nextagentbc/nextclaw).
• docs/INSTALL.md steps ①②④⑤⑦ rewritten to match. Discord, multi-agent
  isolation, reflection, Telegram Moderator, and web_search bolt-on sections
  preserved verbatim.
• docs/SERVICES.md §1 (Postgres) gains the Neon / Docker side-by-side; §7
  (OpenClaw) drops the source-checkout + pnpm instructions.

Documentation bug fixes surfaced by end-to-end dogfood

Two long-standing doc bugs only became visible after dogfooding the new flow
end-to-end on a clean machine.

• Dashboard auth header. The HTTP dashboard validates requests via the
  X-Token header (or ?token= query param). Pre-0.2.1 README/INSTALL
  examples used Authorization: Bearer $TOKEN, which the dashboard treats
  as no token at all and returns 401. All curl examples (/api/ingest,
  /api/recall, /api/reflection/run-now) switched to X-Token. The
  dashboard JS itself was already using X-Token after capturing ?token=
  into sessionStorage, so this was a docs-only fix.
• Daemon env path. openclaw onboard --install-daemon runs the gateway
  via launchd on macOS and systemd-user on Linux. Neither reads ~/.zshrc
  or ~/.bashrc. The daemon sources ~/.openclaw/service-env/ai.openclaw.gateway.env
  on every start. Pre-0.2.1 docs told users to echo "export NEXTCLAW_DASH_TOKEN=…" >> ~/.zshrc, which left the daemon with an empty
  token (dashboard rejected every request) and no JINA_API_KEY (embedding
  client got AUTH_MISSING_API_KEY from Jina). README step 3 and step 6 +
  INSTALL.md step ⑦ now write to the service-env file and keep the
  shell-rc append only for the smoke-test curls.

Validated end-to-end on a clean machine

Full dogfood ran on macOS with no pnpm, no docker, no Node project. Steps
executed exactly as the new docs ship them: brew install colima docker →
colima start → single docker run pgvector/pgvector:pg16 + three
CREATE EXTENSION → openclaw plugins install git:… → configure-minimal.mjs →
openclaw gateway restart. The smoke test then exercises all four recall
behaviours:

• Lexical hit on a keyword-overlapping query → hitTier=t1, embedCalls=0, latencyMs=2
• Semantically equivalent English query with no lexical overlap → hitTier=t2_hybrid, embedCalls=1, latencyMs=379
• Chinese cross-language query → hitTier=t2_hybrid, embedCalls=1, latencyMs=440, score=1.78
• Repeat of any prior query → t1 cache, zeroCostHit=true, latencyMs=2

All four match what the README advertises.

---

---

Install (curl-installed OpenClaw):

openclaw plugins install git:github.com/NextAgentBC/nextclaw@v0.2.1

See README.md for the full 7-step Quick Start (~5 min on Neon, ~10 min on Docker).

v0.1.0 — initial public release

nextclaw 0.1.0 — initial public release

Postgres + pgvector long-term memory plugin for OpenClaw.
4-tier recall · multi-key Xinhua-dictionary indexing · deterministic-first ingest · hard per-agent isolation · real-time dashboard.

Highlights

• 4-tier recall (T0 in-process / T1 PG UNLOGGED / T2 main / T3 cold gist) — most queries return in <5ms with 0 LLM tokens
• 8 parallel routes (semantic / fulltext / trgm / concept_tag / entity_ref / time_bucket / anchor / category) merged via MMR — Xinhua-dictionary mode, every chunk reachable from many angles
• Deterministic-first ingest (Stages 0–6) — LLM only enters as a residual when prior stages produce nothing; in a typical workload, 0 LLM tokens spent on ingest
• Hard per-agent memory isolation — agent_id column threaded through every recall route, T0 working set, and cache scope. Validated with 6 adversarial probes: 0 chunks leaked
• Self-tuning loop — daily / weekly / monthly proposals into audit.tuning_proposals; auto-apply only on safe_auto
• Real-time dashboard — bilingual (CN/EN) panels for ingest decisions, recall tier hits, category distribution, bot turn latency, model comparison, with health/medical excerpts auto-redacted
• Privacy by default — health and medical chunks auto-pinned (importance ≥ 0.7) and redacted in the dashboard

Workers shipped

• transcript-watcher — ingests every conversation turn deterministically, no agent involvement required
• git-watcher — polls a local repo and ingests new commits since last_sha
• shadow-comparator — replays each turn against a challenger chat endpoint (e.g. Qwen 3.6) for side-by-side latency / token / output comparison
• compactor — 90-day rolling cold-gist consolidation
• spreading-activator — Hebbian neighbor warmth bump on recall
• tuning — scheduled proposal analyzer (cron-style)

API endpoints

/api/stats · /api/recent · /api/stream (SSE) · /api/ingest · /api/recall · /api/bot-stats · /api/model-compare

Install

cd dev/ && docker compose up -d        # Postgres + pgvector on 127.0.0.1:55432
cd /path/to/openclaw/extensions
git clone https://github.com/NextAgentBC/nextclaw.git memory-postgres
cd /path/to/openclaw && pnpm install && pnpm build

Then point plugins.slots.memory at memory-postgres in your ~/.openclaw/openclaw.json. See README for the full config example, multi-agent setup, and dashboard token flow.

Compatibility

• OpenClaw >= 2026.4.25
• Node >= 22
• Postgres >= 16 with pgvector >= 0.7.0
• Embedding: any OpenAI- or Ollama-compat endpoint (Qwen3-embedding 4096-d and nomic-embed-text 768-d both tested)

License

Apache 2.0 · acknowledges OpenClaw upstream in NOTICE