\n\n# AnchorClaw - Reliable Postgres Memory for OpenClaw\n\n**No more \"the agent forgot everything again.\"**\n\nAnchorClaw turns OpenClaw memory into real application state: PostgreSQL-backed,\ninspectable, migratable, and aware of agent workspace boundaries.\n\nDurable facts, daily context, session continuity, import state, and search live\nbehind one reliable database layer. OpenClaw keeps its familiar memory tools and\nfile-shaped paths. Full-text search works without embeddings, while optional\nsemantic retrieval improves recall without becoming the source of truth.\n\n[Quick Start](#quick-start) · [Installation Guide](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/INSTALL.md) ·\n[Architecture](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/ARCHITECTURE.md)\n\n## From Memory Files to Memory Infrastructure\n\nFile memory is transparent and useful. It is also easy to outgrow once an agent\nruns for weeks, survives resets, or shares a host with other agents.\n\n| Before AnchorClaw | With AnchorClaw |\n| --- | --- |\n| Durable knowledge drifts across Markdown files and sessions. | Durable and daily memory are DB-backed and auditable. |\n| `/new`, `/reset`, and compaction can scatter useful context. | Session capture and controlled compaction flushes feed one daily memory layer. |\n| `MEMORY.md` grows noisy, stale, and difficult to repair. | `MEMORY.md` becomes a virtual snapshot generated from PostgreSQL. |\n| Search depends on files or an embedding provider. | PostgreSQL FTS is always available; semantic recall is optional. |\n| One global plugin workspace becomes ambiguous with several agents. | Memory scope follows OpenClaw agent/workspace routing. |\n| Imports and background jobs can process the same workspace twice. | Explicit targets and resolved-path deduplication make ownership predictable. |\n\nAnchorClaw is built around one principle: **durable memory should be durable\nfirst**. Storage, deterministic writes, migrations, provenance, and lexical\nsearch come before semantic similarity.\n\n## What You Get\n\n- **Memory that survives**: durable facts, preferences, rules, and notes remain\n available across sessions, gateway restarts, `/new`, `/reset`, and\n compaction.\n- **SQL-first retrieval**: PostgreSQL full-text search works out of the box,\n with stable ordering and no embedding provider required.\n- **Safe daily context**: daily writes use immutable append blocks for\n provenance and a canonical DB view for prompts, search, and file-shaped\n compatibility.\n- **OpenClaw memory compatibility**: `memory_store`, `memory_log`,\n `memory_search`, `memory_get`, `memory_forget`, `memory_status`, virtual\n `MEMORY.md`, and DB-backed daily paths remain available through the normal\n OpenClaw memory capability.\n- **Multi-agent workspace boundaries**: separate workspace paths map to\n isolated DB scopes; agents that intentionally share a workspace share one\n memory scope.\n- **No duplicate workspace processing**: import and maintenance targets are\n deduplicated by resolved workspace path, not merely by agent name.\n- **Safe legacy migration**: inspect before applying, select the destination\n explicitly, archive imported files, and fail closed when a migration is\n incomplete.\n- **Controlled daily-to-durable promotion**: optional maintenance can extract\n high-confidence durable candidates from bounded, versioned `memory_log`\n windows.\n- **Operational visibility**: health, migration state, import state, semantic\n queues, and degraded behavior are visible through `memory_status`, tool\n details, PostgreSQL, and logs.\n- **Version-aware sessions search**: legacy OpenClaw hosts can use the opt-in\n Postgres transcript index, with AnchorClaw's configured scope intersected\n with OpenClaw's `tools.sessions.visibility` security guard; OpenClaw\n `>=2026.8.1-beta.1` owns session recall through its native `sessions_search`\n and SQLite index. On native hosts, `tools.sessions.visibility` is the sole\n session-access policy; AnchorClaw's legacy `sessions.*` settings are not\n translated into it.\n\n## How It Works\n\n```text\nOpenClaw tools, prompts, reset and compaction lifecycle\n |\n v\n AnchorClaw memory capability\n |\n +-----------+-----------+\n | |\n v v\n PostgreSQL FTS Optional pgvector\n | semantic enrichment\n +-----------+-----------+\n |\n v\n PostgreSQL source of truth\n - durable memory\n - daily memory\n - session index\n - import/maintenance state\n```\n\n`MEMORY.md` is a virtual DB-backed snapshot. `memory/YYYY-MM-DD.md` is a\nDB-backed daily view. Existing OpenClaw-style instructions can keep referring to\nthose paths while AnchorClaw owns the actual reads and writes.\n\nDaily memory is append-safe: immutable blocks preserve where each write came\nfrom, while a canonical projection gives prompts and tools one current document\nper day. `/new` and `/reset` captures use the same DB-backed layer. Before\ncompaction, important context can pass through a controlled flush inbox and be\nrecovered into PostgreSQL.\n\nFor the table model, lifecycle hooks, search corpuses, and failure boundaries,\nsee [ARCHITECTURE.md](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/ARCHITECTURE.md).\n\n## Multi-Agent by Design\n\nAnchorClaw does not keep one global plugin workspace. Runtime scope follows the\nactive OpenClaw agent's resolved workspace.\n\n```text\nagent main -> /work/main -> DB workspace A\nagent ops -> /work/ops -> DB workspace B\nagent qa -> /work/shared -> DB workspace C\nagent test -> /work/shared -> DB workspace C\n```\n\n- `main` and `ops` remain isolated because their workspace paths differ.\n- `qa` and `test` intentionally share memory because they resolve to the same\n path.\n- Shared paths are processed once during all-workspace import and maintenance.\n- Imports target the default agent, one configured agent, or all unique agent\n workspaces explicitly.\n- Background maintenance uses an explicit workspace scope instead of guessing.\n\nUser identity and workspace identity are separate boundaries. For Docker,\nmultiple machines, or long-lived deployments, configure a stable\n`identity.externalId`; workspace isolation continues to follow resolved\nOpenClaw workspace paths.\n\nSee the full routing contract and workspace matrix in\n[ARCHITECTURE.md#multi-agent-workspace-model](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/ARCHITECTURE.md#multi-agent-workspace-model).\n\n## SQL First, Semantic When You Want It\n\nAnchorClaw is not anti-embeddings. It is anti-\"embeddings are the database.\"\n\nWithout semantic retrieval, the complete durable and daily runtime remains\navailable through PostgreSQL and FTS. With semantic enabled, AnchorClaw adds\npgvector-backed recall for durable `memory_items` and combines lexical and\nvector ranks during `memory_search`.\n\n- Durable writes commit before best-effort embedding work.\n- Missing or stale embeddings are indexed on demand in bounded batches.\n- Remaining work is represented by lightweight maintenance requests.\n- Provider, key, schema, or vector failures degrade back to lexical search.\n- Daily memory and sessions remain lexical in the current release.\n- `memory_status(check=true)` can actively verify the configured embedding\n provider without writing a memory item.\n\nThe semantic layer is a derived index. PostgreSQL `memory_items` remains the\ndurable source of truth.\n\n## Built for Operational Failure\n\nAnchorClaw makes failure modes explicit instead of hiding them behind prompts:\n\n- an unavailable embedding provider leaves SQL/FTS retrieval working;\n- an incomplete import reports failure instead of claiming clean migration;\n- active legacy files are detected and reported;\n- startup drains recoverable compaction flushes into the DB;\n- maintenance processes bounded windows and records completed work;\n- one workspace failure is isolated from other selected maintenance targets;\n- semantic indexing requests survive restart and are retried by maintenance;\n- extractor policy is separated from quoted daily text, which is treated as\n untrusted input before durable promotion.\n\nNormal PostgreSQL backups, migrations, queries, and audit review remain\navailable because memory is stored as application data rather than opaque\nprompt state.\n\n## Quick Start\n\nRequirements:\n\n- OpenClaw `>= 2026.5.28`\n- Node.js\n- PostgreSQL\n\nInstall AnchorClaw:\n\n```bash\nopenclaw plugins install clawhub:@alexandrgreen/anchorclaw\n```\n\nUse `npm:@alexandrgreen/anchorclaw` if you explicitly need the npm fallback.\n\nVerify that the plugin is active as the OpenClaw memory slot owner:\n\n```bash\nopenclaw plugins inspect anchorclaw\n```\n\nIf it is installed but not active, enable it:\n\n```bash\nopenclaw plugins enable anchorclaw\n```\n\nProvision PostgreSQL and update the OpenClaw config:\n\n```bash\nopenclaw anchorclaw setup\n```\n\nRestart the gateway:\n\n```bash\nopenclaw gateway restart\n```\n\nIf legacy `MEMORY.md` or `memory/YYYY-MM-DD.md` files exist, inspect the import\nplan and then apply it:\n\n```bash\nopenclaw anchorclaw import\nopenclaw anchorclaw import --apply\n```\n\nSetup can optionally configure a semantic provider and provision PostgreSQL\n`vector`. Initial semantic provisioning requires a PostgreSQL admin connection;\nthe restarted gateway applies AnchorClaw's semantic table migrations through\nthe configured app user.\n\n### After Upgrading OpenClaw or AnchorClaw\n\nNew host versions can require config that an existing install does not have\nyet. Reconcile it and restart:\n\n```bash\nopenclaw anchorclaw update\nopenclaw gateway restart\n```\n\n`update` only touches `openclaw.json`. It never connects to PostgreSQL, so it\nneeds no admin credentials, and it leaves database, maintenance, and semantic\nsettings alone. Add `--dry-run` to see the changes first.\n\nThis matters most for OpenClaw `>= 2026.7.2-beta.6`, which refuses AnchorClaw's\nprompt-injection hook unless\n`plugins.entries.anchorclaw.hooks.allowConversationAccess` is `true`. Without\nit, long-term memory stops reaching the prompt and nothing appears to be\nbroken. See [Installation and Configuration](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/INSTALL.md).\n\nFor non-interactive setup, Docker identity, semantic providers, SSL, pool\ntuning, import selectors, manual provisioning, and SQL-only-to-semantic\nupgrades, use the [Installation and Configuration Guide](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/INSTALL.md).\n\n## Documentation\n\n- [Installation and Configuration](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/INSTALL.md) - setup, semantic opt-in,\n legacy import, identity, SSL, pool tuning, and manual PostgreSQL provisioning.\n- [Architecture](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/ARCHITECTURE.md) - data model, runtime contracts, lifecycle,\n multi-agent routing, maintenance/extractor, and semantic enrichment.\n- [Changelog](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/CHANGELOG.md) - release history and compatibility notes.\n- [TweetClaw source memory workflow](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/docs/integrations/tweetclaw.md) - community\n integration notes for TweetClaw/Xquik users. Those projects are maintained\n separately from AnchorClaw.\n\n## Maintainer and License\n\nAnchorClaw is created and maintained by\n[Alexander Green](https://github.com/Alexander-Green).\n\nLicensed under the [MIT License](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/LICENSE). See [NOTICE](https://github.com/Alexander-Green/anchorClaw/blob/v0.1.4/NOTICE) for\nadditional attribution.\n\nIf AnchorClaw makes your agents more reliable, consider starring the\n[repository](https://github.com/Alexander-Green/anchorClaw).\n","readmeFilename":"README.md"}
![\"AnchorClaw](\"./assets/logo.png\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/@alexandrgreen/anchorclaw\")
![\"MIT](\"https://img.shields.io/npm/l/@alexandrgreen/anchorclaw\")
![\"OpenClaw](\"https://img.shields.io/badge/OpenClaw-%3E%3D2026.5.28-1f6f5c\"){kind=icon}
![\"PostgreSQL\"](\"https://img.shields.io/badge/PostgreSQL-backed-336791\"){kind=icon}