{"id":45614276,"url":"https://github.com/phenomenoner/openclaw-mem","last_synced_at":"2026-04-29T03:07:59.068Z","repository":{"id":336777088,"uuid":"1149714756","full_name":"phenomenoner/openclaw-mem","owner":"phenomenoner","description":"Trust-aware context packing + review-gated memory hygiene for OpenClaw.","archived":false,"fork":false,"pushed_at":"2026-04-27T02:20:54.000Z","size":5061,"stargazers_count":28,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T03:31:24.273Z","etag":null,"topics":["agent-memory","context-engineering","llmops","local-first","memory-systems","observability","openclaw","openclaw-plugin","prompt-packing","provenance","sqlite"],"latest_commit_sha":null,"homepage":"https://phenomenoner.github.io/openclaw-mem/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phenomenoner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-04T12:43:01.000Z","updated_at":"2026-04-27T02:20:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phenomenoner/openclaw-mem","commit_stats":null,"previous_names":["phenomenoner/openclaw-mem"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/phenomenoner/openclaw-mem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fopenclaw-mem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fopenclaw-mem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fopenclaw-mem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fopenclaw-mem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phenomenoner","download_url":"https://codeload.github.com/phenomenoner/openclaw-mem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fopenclaw-mem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32408488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T02:37:21.628Z","status":"ssl_error","status_checked_at":"2026-04-29T02:36:50.947Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","context-engineering","llmops","local-first","memory-systems","observability","openclaw","openclaw-plugin","prompt-packing","provenance","sqlite"],"created_at":"2026-02-23T17:58:47.792Z","updated_at":"2026-04-29T03:07:59.063Z","avatar_url":"https://github.com/phenomenoner.png","language":"Python","readme":"# openclaw-mem\n\n**Memory your agent can’t lie about — a local context supply chain you can grep, diff, and roll back.**\n\n`openclaw-mem` turns agent work into a durable, searchable, auditable memory trail, then assembles bounded context bundles that are small enough to inject and easy to verify. Start with a local SQLite sidecar beside OpenClaw, keep your current memory backend, and promote to the optional mem engine only when hybrid recall and policy controls earn their keep.\nWhen you do promote the engine, the live-turn hook is framed as **Proactive Pack**: bounded pre-reply recall orchestration, not a separate hidden memory layer.\n\n## Start here\n\n1. **Verify locally in ~60 seconds:** [Reality check \u0026 status](docs/reality-check.md)\n2. **Run the CLI path:** [Quickstart](QUICKSTART.md)\n3. **Choose sidecar vs engine:** [Install modes](docs/install-modes.md)\n4. **Check what is automatic:** [Automation status](docs/automation-status.md)\n5. **See the product gaps:** [OpenClaw user improvement roadmap](docs/openclaw-user-improvement-roadmap.md)\n6. **Read in Traditional Chinese:** [Traditional Chinese edition](docs/zh/index.md)\n\n## What is automatic today?\n\n| Surface | Status | Meaning |\n| --- | --- | --- |\n| Sidecar observation capture | Automatic when the plugin is enabled | Captures denoised JSONL observations and backend/action annotations. |\n| Harvest, triage, and graph capture | Scheduled on configured hosts | Converts captured records into searchable stores and receipts. |\n| `pack`, graph routing, optimize assist, continuity | CLI / opt-in lanes | Available, but not assumed to run in every live agent turn. |\n| Mem-engine Proactive Pack | Optional promotion | Bounded pre-reply recall orchestration after explicit engine adoption. |\n\n## What you get\n\n- **Local-first by default** — JSONL + SQLite, no external database required.\n- **Cheap recall loop** — `search → timeline → get` keeps routine lookups fast and inspectable.\n- **Bounded packing** — `pack` emits a stable `ContextPack` contract for injection, citations, graph-aware synthesis preference, protected fresh tails, and trace-backed debugging.\n- **Fits real OpenClaw ops** — capture tool outcomes, retain receipts, sanitize runtime artifacts, and keep rollback simple.\n- **Upgradeable path** — sidecar first, engine later; no forced migration on day one.\n- **Governed continuity side-car** — optional `continuity` surface for derived self/continuity inspection, adjudication, public-safe summaries, and explicit weaken/rebind/retire receipts.\n\n## Why this exists\n\nLong-running agents do not just forget. They also accumulate memory that quietly degrades:\n\n- old notes still match the query even when they are no longer useful\n- untrusted or hostile content can retrieve well and slip into context\n- prompts bloat into giant memory dumps instead of a small, inspectable bundle\n- when something goes wrong, it is hard to explain **why** a memory was included\n\n`openclaw-mem` tackles that by building compact memory packs with citations, trace receipts, and trust-policy controls.\n\n## Try it in 5 minutes\n\nYou can prove the core behavior locally without touching OpenClaw config.\n\n```bash\ngit clone https://github.com/phenomenoner/openclaw-mem.git\ncd openclaw-mem\nuv sync --locked\n\nDB=/tmp/openclaw-mem-proof.sqlite\nuv run --python 3.13 --frozen -- python -m openclaw_mem ingest \\\n  --db \"$DB\" \\\n  --json \\\n  --file ./docs/showcase/artifacts/trust-aware-context-pack.synthetic.jsonl\n\nuv run --python 3.13 --frozen -- python -m openclaw_mem pack \\\n  --db \"$DB\" \\\n  --query \"trust-aware context packing prompt pack receipts hostile durable memory provenance\" \\\n  --limit 5 \\\n  --budget-tokens 500 \\\n  --trace\n```\n\n### What this proof shows\n\n- the same query can change its result set when a trust policy is applied\n- quarantined content can be excluded with an explicit reason\n- every include/exclude decision stays inspectable through receipts and trace output\n\nFull proof path:\n- [Trust-aware pack proof](docs/showcase/trust-aware-context-pack-proof.md)\n- [Command-aware compaction proof](docs/showcase/command-aware-compaction-proof.md)\n- [Metrics JSON](docs/showcase/artifacts/trust-aware-context-pack.metrics.json)\n- [Synthetic fixture + receipts](docs/showcase/artifacts/index.md)\n- [Inside-out demo](docs/showcase/inside-out-demo.md)\n\n## Store + Pack + Observe\n\nThe product loop is simple and stable:\n\n1. **Store**: capture, ingest, and query observations with `store`/`ingest`/`search`.\n2. **Pack**: run `pack` to get a bounded `bundle_text` and `context_pack` (`schema: openclaw-mem.context-pack.v1`), with optional protected-tail continuity and graph-aware synthesis preference.\n3. **Observe**: use `timeline`, `get`, and `artifact` outputs for explainability and rollback.\n\nWhen mem-engine is active, **Proactive Pack** extends the same Pack contract into live turns as a small, receipt-backed pre-reply bundle.\n\n## Experimental GBrain sidecar\n\n`openclaw-mem` also ships an **experimental GBrain sidecar**.\nIt is **not enabled by default**, carries **no stability guarantee**, and is still documented as an experimental rollout rather than a default product path.\n\nFor teams that want to test two bounded additions, it currently offers:\n\n- a **read-only GBrain lookup** that can add extra Pack candidates without changing `ContextPack`\n- a **restricted background-job bridge** for one deterministic helper lane at a time\n\nUse it when you want to evaluate whether GBrain can improve retrieval support or bounded helper execution without changing memory ownership.\nDo not treat it as a second truth store, a backend replacement, or a general-purpose job runner.\n\nRead more:\n- [Experimental GBrain sidecar](docs/experimental/gbrain-sidecar/README.md)\n- [Optional Mem Engine + GBrain mirror](docs/mem-engine.md)\n\n## Governed continuity side-car\n\n`openclaw-mem` also ships an optional derived continuity lane.\nThis is not a second truth store, and it is not presented as consciousness.\nIt is a governed side-car that helps operators inspect what continuity claims the system is currently making, how strong those claims are allowed to be, and when those claims should be weakened, rebound, or retired.\n\nCore operator surfaces:\n\n```bash\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity current --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity attachment-map --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity adjudication --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity public-summary --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity explain --snapshot \u003csnapshot.json\u003e --stance \u003cid\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity sensitivity --snapshot \u003csnapshot.json\u003e --stance \u003cid\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity patterns --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity triggers --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity interventions --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity compare-sessions --left-scope \u003cscope-a\u003e --left-session-id \u003csession-a\u003e --right-scope \u003cscope-b\u003e --right-session-id \u003csession-b\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity wording-lint --snapshot \u003csnapshot.json\u003e --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity release-history --json\n```\n\nControl-plane activation is explicit and starts autonomous snapshot + receipt generation under `~/.openclaw/memory/openclaw-mem/self-model-sidecar/` until you disable it:\n\n```bash\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity enable --cadence-seconds 300 --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity status --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem continuity disable --json\n```\n\nFor the real 72h endurance gate, run the self-closing soak controller instead of hand-counting receipts. It advances one autorun cycle per wake, writes status under `~/.openclaw/memory/openclaw-mem/self-model-sidecar/soak/`, emits a clear warning on anomalous gaps/drift, and disables its own cron job after a healthy 72h window closes:\n\n```bash\npython3 tools/self_model_sidecar_soak_controller.py \\\n  --repo-root /root/.openclaw/workspace/openclaw-mem \\\n  --run-dir /root/.openclaw/memory/openclaw-mem/self-model-sidecar \\\n  --cadence-seconds 300 \\\n  --target-hours 72\n```\n\nUse it when you need auditable continuity receipts, migration comparison, or public-safe hedged summaries, not when you need a new source of truth. The lane stays rebuildable from memory-of-record by design.\n\nUpdated operator loop:\n- `continuity explain` answers why one claim exists, including adjudication reasons and release history.\n- `continuity sensitivity` measures fragility by removing top evidence and recomputing the claim state.\n- `continuity patterns`, `triggers`, and `interventions` turn persisted receipts into a governed operator loop instead of raw JSON archaeology.\n- `continuity wording-lint` catches selfhood inflation and missing hedges before copy leaves the operator lane.\n\nExample:\n\n```bash\nuv run --python 3.13 --frozen -- python -m openclaw_mem pack \"What changed this week?\" --limit 6 --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem artifact stash --from ./tool-output.txt --json\nuv run --python 3.13 --frozen -- python -m openclaw_mem artifact peek ocm_artifact:v1:sha256:\u003c64hex\u003e --json\n```\n\n## OpenClaw 2026.4.15 and `openclaw-mem`\n\nBy OpenClaw 2026.4.15, the native memory and prompt-time integration experience had become noticeably stronger. We are genuinely happy to see that direction mature.\n\nThat is good for the ecosystem, good for operators, and good for `openclaw-mem` too.\nA stronger foundation makes it easier to keep our own work focused on what matters most: better packs, clearer evidence, and safer memory maintenance.\n\nOur direction is not to shrink back into native features.\nIt is to build a clearer, more opinionated product layer on top of a stronger foundation.\n\nRead more:\n- [Why openclaw-mem still exists in a stronger OpenClaw world](docs/why-openclaw-mem-still-exists.md)\n- [openclaw-mem and OpenClaw 2026.4.15](docs/openclaw-2026-4-15-comparison.md)\n\n## Governed optimization updates\n\n`openclaw-mem` now ships a review-first workflow for one low-risk class of memory maintenance updates.\n\nCurrent shipped path:\n- `openclaw-mem optimize review` — read-only health signals\n- `openclaw-mem optimize evolution-review` — prepares low-risk maintenance candidates\n- `openclaw-mem optimize governor-review` — records explicit decisions\n- `openclaw-mem optimize assist-apply` — applies only approved low-risk observation updates with before/after and rollback receipts\n\nEach assist apply run now also emits a compact effect artifact so later autonomy phases can measure whether mutations helped, held steady, or regressed instead of treating writes as blind maintenance.\n\nThe first bounded write class is intentionally narrow:\n- update `observations.detail_json.lifecycle.stale_candidate`\n- update `observations.detail_json.lifecycle.stale_reason_code`\n- update `observations.detail_json.importance.score`\n- update `observations.detail_json.importance.label`\n- add bounded `observations.detail_json.optimization.assist` metadata\n\nExample dry rehearsal:\n\n```bash\nuv run --python 3.13 --frozen -- python -m openclaw_mem optimize evolution-review --json \u003e evolution.json\nuv run --python 3.13 --frozen -- python -m openclaw_mem optimize governor-review --from-file evolution.json --approve-stale --approve-importance --json \u003e governor.json\nuv run --python 3.13 --frozen -- python -m openclaw_mem optimize assist-apply --from-file governor.json --dry-run --json\n```\n\nExample bounded write run:\n\n```bash\nuv run --python 3.13 --frozen -- python -m openclaw_mem optimize assist-apply --from-file governor.json --json\n```\n\nScheduled worker form:\n\n```bash\nuv run --python 3.13 --frozen -- python tools/optimize_assist_runner.py --json\n```\n\nThat runner keeps the full packet chain in one bounded scheduled surface and stays dry-run unless `--allow-apply` is set.\n\nReceipts are written under `~/.openclaw/memory/openclaw-mem/optimize-assist/` by default.\nIf the packet is malformed, unapproved, duplicated, or exceeds caps, the run aborts before write.\n\n### Command-aware compaction, minimal operator path\n\nIf you already use a compactor such as RTK, keep it in the Observe path first:\n\n```bash\n# 1) Produce raw + compact outputs with your own toolchain\nmy-compactor git diff --stat \u003e ./compact-git-diff.txt\ngit diff --stat \u003e ./raw-git-diff.txt\n\n# 2) Bind them into a sideband receipt\nuv run --python 3.13 --frozen -- python -m openclaw_mem artifact compact-receipt \\\n  --command \"git diff --stat\" \\\n  --tool my-compactor \\\n  --compact-file ./compact-git-diff.txt \\\n  --raw-file ./raw-git-diff.txt \\\n  --json \u003e ./compaction-receipt.json\n\n# 3) Recover bounded raw evidence later, from the receipt or raw handle\nuv run --python 3.13 --frozen -- python -m openclaw_mem artifact rehydrate \\\n  --receipt-file ./compaction-receipt.json \\\n  --max-chars 1200 \\\n  --json\n```\n\nWhen a compaction receipt is later selected by `pack`, the response may include:\n- `compaction_sideband` for raw recovery metadata\n- `compaction_policy_hints` for advisory family-level guidance (`git_diff`, `test_failures`, `long_logs`, `generic`)\n- `trace.extensions.compaction_sideband` / `compaction_policy_hints` for auditable preference receipts\n\n## Start here\n\n- **Why openclaw-mem still exists:** [`docs/why-openclaw-mem-still-exists.md`](docs/why-openclaw-mem-still-exists.md)\n- **OpenClaw 2026.4.15 comparison:** [`docs/openclaw-2026-4-15-comparison.md`](docs/openclaw-2026-4-15-comparison.md)\n- **About the product:** [`docs/about.md`](docs/about.md)\n- **Proactive Pack:** [`docs/proactive-pack.md`](docs/proactive-pack.md)\n- **v2 blueprint:** [`docs/context-supply-chain-blueprint.md`](docs/context-supply-chain-blueprint.md)\n- **Choose an install path:** [`docs/install-modes.md`](docs/install-modes.md)\n- **Detailed quickstart:** [`QUICKSTART.md`](QUICKSTART.md)\n- **Docs site:** \u003chttps://phenomenoner.github.io/openclaw-mem/\u003e\n- **Traditional Chinese edition:** [`docs/zh/index.md`](docs/zh/index.md)\n- **Reality check / status:** [`docs/reality-check.md`](docs/reality-check.md)\n- **Deployment patterns:** [`docs/deployment.md`](docs/deployment.md)\n- **Experimental GBrain sidecar:** [`docs/experimental/gbrain-sidecar/README.md`](docs/experimental/gbrain-sidecar/README.md)\n- **Continuity side-car ops lane:** [`skills/self-model-sidecar.ops.md`](skills/self-model-sidecar.ops.md)\n- **GBrain sidecar ops lane:** [`skills/gbrain-sidecar.ops.md`](skills/gbrain-sidecar.ops.md)\n- **Auto-capture plugin:** [`docs/auto-capture.md`](docs/auto-capture.md)\n- **Agent memory skill (SOP):** [`docs/agent-memory-skill.md`](docs/agent-memory-skill.md)\n- **Pack policy contract:** [`docs/specs/context-pack-policy-v1.1.md`](docs/specs/context-pack-policy-v1.1.md)\n- **Optional Mem Engine:** [`docs/mem-engine.md`](docs/mem-engine.md)\n- **Release notes:** \u003chttps://github.com/phenomenoner/openclaw-mem/releases\u003e\n\n## License\n\nDual-licensed: **MIT OR Apache-2.0**. See `LICENSE`, `LICENSE-MIT`, and `LICENSE-APACHE`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenomenoner%2Fopenclaw-mem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphenomenoner%2Fopenclaw-mem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenomenoner%2Fopenclaw-mem/lists"}