Metadata-Version: 2.4
Name: openclaw-context-pack
Version: 1.9.24
Summary: Local-first AI agent memory governance: Store / Pack / Observe with citations, receipts, and rollback
License: MIT OR Apache-2.0
License-File: LICENSE
License-File: LICENSE-APACHE
License-File: NOTICE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Description-Content-Type: text/markdown

# openclaw-mem

**Local-first context supply chain for AI agents — Store / Pack / Observe with citations, trust-policy receipts, and rollback.**

`openclaw-mem` captures agent activity as durable local records, then assembles bounded `ContextPack` bundles with inspectable include/exclude reasons and citation coverage. Use it first as a plain SQLite sidecar; promote to deeper OpenClaw integration only after the local proof earns the extra surface.

## Start here

1. **Run the synthetic proof:** [Trust-policy synthetic proof](docs/showcase/trust-policy-synthetic-proof.md)
2. **Pick an evaluation path:** [5 minutes / 30 minutes / one afternoon](docs/evaluator-path.md)
3. **Check Core vs Advanced Labs:** [Core vs Advanced Labs](docs/core-vs-advanced-labs.md)
4. **Choose sidecar vs engine:** [Install modes](docs/install-modes.md)
5. **Check shipped vs partial status:** [Reality check & status](docs/reality-check.md)
6. **Read in Traditional Chinese:** [Traditional Chinese edition](docs/zh/index.md)

## What is automatic today?

| Surface | Status | Meaning |
| --- | --- | --- |
| Sidecar observation capture | Automatic when the plugin is enabled | Captures JSONL observations with backend/action annotations. |
| Harvest, triage, and graph capture | Scheduled on configured hosts | Converts captured records into searchable stores and receipts. |
| `pack` | CLI core | Produces bounded `ContextPack` output with citations and trace receipts. |
| Harness-persistent memory | Opt-in via Gateway + CLI install card | Installs a persistent Codex / Claude / Gemini / generic agent memory posture backed by capability-scoped gateway tokens and parity-aware read diagnostics. |
| Graph routing, optimize assist, continuity, GBrain | Advanced Labs / opt-in lanes | Available for mature operators, but not part of the first evaluation path. |
| Mem-engine Proactive Pack | Optional promotion | Bounded pre-reply recall orchestration after explicit engine adoption. |

## Why it is different

- **Governance before recall theater** — trust policy, citations, trace receipts, and rollback posture make memory inclusion inspectable instead of opaque.
- **Local-first by default** — JSONL + SQLite, no external database required.
- **Cheap recall loop** — `search → timeline → get` keeps routine lookups fast and inspectable.
- **Bounded packing** — `pack` emits a stable `ContextPack` contract for injection, citations, trust-policy receipts, and trace-backed debugging.
- **Symbolic canvas helper** — `symbolic-canvas` can turn task traces into compact Mermaid + `node_id` drill-down artifacts without live capture, Gateway patching, or memory mutation.
- **Fits real OpenClaw ops** — capture tool outcomes, retain receipts, sanitize runtime artifacts, and keep rollback simple.
- **Upgradeable path** — sidecar first, engine later; no forced migration on day one.
- **Harness-friendly** — external coding agents can get a persistent memory posture through the Memory Gateway without receiving raw SQLite or workspace-file authority. Parity-aware gateway reads can search/pack configured workspace Markdown memory and report when a no-result answer is only partial.
- **Advanced labs are opt-in** — graph routing, GBrain, continuity, Dream Lite, Self Curator review packets, and deeper optimization lanes stay out of the first evaluation path.

## Why this exists

Long-running agents do not just forget. They also accumulate memory that quietly degrades:

- old notes still match the query even when they are no longer useful
- untrusted or hostile content can retrieve well and slip into context
- prompts bloat into giant memory dumps instead of a small, inspectable bundle
- when something goes wrong, it is hard to explain **why** a memory was included

`openclaw-mem` tackles that by building compact memory packs with citations, trace receipts, and trust-policy controls.

## Try it in 5 minutes

You can prove the core behavior locally without touching OpenClaw config.

For the packaged CLI:

```bash
python -m venv .venv
. .venv/bin/activate
pip install openclaw-context-pack
openclaw-mem --db /tmp/openclaw-mem-demo.sqlite status --json
```

For the repository proof fixture:

```bash
git clone https://github.com/phenomenoner/openclaw-mem.git
cd openclaw-mem
uv sync --locked

uv run --python 3.13 --frozen -- \
  python benchmarks/trust_policy_synthetic_proof.py --json
```

### What this proof shows

- vanilla packing selects a quarantined row from synthetic memory
- trust-aware packing excludes that row with an explicit reason
- selected rows keep citation coverage and traceable receipts

Full proof path:
- [Evaluator path](docs/evaluator-path.md)
- [Trust-policy synthetic proof](docs/showcase/trust-policy-synthetic-proof.md)
- [Trust-aware pack proof](docs/showcase/trust-aware-context-pack-proof.md)
- [Command-aware compaction proof](docs/showcase/command-aware-compaction-proof.md)
- [Metrics JSON](docs/showcase/artifacts/trust-aware-context-pack.metrics.json)
- [Synthetic fixture + receipts](docs/showcase/artifacts/index.md)
- [Inside-out demo](docs/showcase/inside-out-demo.md)

## Store + Pack + Observe

The product loop is simple and stable:

1. **Store**: capture, ingest, and query observations with `store`/`ingest`/`search`.
2. **Pack**: run `pack` to get a bounded `bundle_text` and `context_pack` (`schema: openclaw-mem.context-pack.v1`), with citations, trust policy, and trace receipts.
3. **Observe**: use `timeline`, `get`, and `artifact` outputs for explainability and rollback.

When mem-engine is active, **Proactive Pack** extends the same Pack contract into live turns as a small, receipt-backed pre-reply bundle.

For external AI harnesses, `openclaw-mem harness install` writes a managed persistent instruction card for Codex, Claude, Gemini, or a generic agent surface. The card points the harness at `OPENCLAW_MEM_GATEWAY_URL` / `OPENCLAW_MEM_GATEWAY_TOKEN`; raw tokens are never written into prompt files. Capability-scoped tokens let operators choose read-only, proposal/append write, admin, or owner-equivalent direct-store authority. For Codex specifically, `openclaw-mem codex install` adds a stronger Superpowers-style surface with generated CLI shims, env/gateway checks, and `codex doctor` verification.

Read more: [Harness-persistent memory install](docs/harness-persistent-memory.md) and the release notes for version-specific gateway behavior.

## Advanced labs

The first-time evaluator path is **Store / Pack / Observe**. Everything below is opt-in after the core proof is clear.

Advanced lanes currently include:

- **Graph routing** for topology-aware recall experiments.
- **GBrain sidecar** for bounded read-only lookup and restricted helper-job experiments.
- **Governed continuity side-car** for derived continuity inspection and public-safe summaries.
- **Dream Lite / deeper optimize loops** for research-grade memory maintenance workflows.
- **Self Curator engine** for checkpointed skill lifecycle review/apply loops. The current scheduled lane can mutate `SKILL.md` body sections with rollback receipts; memory/dream/authority expansion remains gated behind explicit review.

These lanes are not required for the 5-minute proof, the sidecar install path, or the basic `ContextPack` contract. Treat them as labs until your use case needs them.

Read more:
- [Product positioning](PRODUCT_POSITIONING.md)
- [Compounding Context OS roadmap](docs/compounding-context-os.md)
- [Core vs Advanced Labs](docs/core-vs-advanced-labs.md)
- [Evaluator path](docs/evaluator-path.md)
- [Architecture](docs/architecture.md)
- [Context pack](docs/context-pack.md)
- [Symbolic Canvas](docs/symbolic-canvas.md)
- [Symbolic canvas ops skill card](skills/symbolic-canvas.ops.md)
- [Experimental GBrain sidecar](docs/experimental/gbrain-sidecar/README.md)
- [Optional Mem Engine](docs/mem-engine.md)

## OpenClaw 2026.4.15 and `openclaw-mem`

By 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.

That is good for the ecosystem, good for operators, and good for `openclaw-mem` too.
A stronger foundation makes it easier to keep our own work focused on what matters most: better packs, clearer evidence, and safer memory maintenance.

Our direction is not to shrink back into native features.
It is to build a clearer, more opinionated product layer on top of a stronger foundation.

Read more:
- [Why openclaw-mem still exists in a stronger OpenClaw world](docs/why-openclaw-mem-still-exists.md)
- [openclaw-mem and OpenClaw 2026.4.15](docs/openclaw-2026-4-15-comparison.md)

## Deeper operations live below the fold

`openclaw-mem` also has governed memory-hygiene and artifact-observation tools for mature operator stacks. They are useful after the core product is proven, but they are not required for the first evaluation path.

Start with:

- [Core vs Advanced Labs](docs/core-vs-advanced-labs.md)
- [Evaluator path](docs/evaluator-path.md)
- [Governed optimize assist](docs/optimize-assist.md)
- [Hermes Curator adoption review](docs/hermes-curator-adoption-review.md)
- [Self Curator v0 review-only sidecar contract](docs/specs/self-curator-sidecar-v0.md)
- [Command-aware compaction proof](docs/showcase/command-aware-compaction-proof.md)

Manual Self Curator scout smoke:

```bash
openclaw-mem self-curator skill-review \
  --skill-root ~/.openclaw/workspace/skills \
  --out-root .state/self-curator/runs \
  --json
```

Checkpointed Self Curator apply flow:

```bash
openclaw-mem self-curator plan --mutations-file mutations.json --out plan.json --workspace-root . --json
openclaw-mem self-curator apply --plan plan.json --workspace-root . --checkpoint-root .state/self-curator/checkpoints --receipt-root .state/self-curator/apply-runs --json
openclaw-mem self-curator verify --receipt .state/self-curator/apply-runs/<run>/apply-receipt.json --json
openclaw-mem self-curator rollback --receipt .state/self-curator/apply-runs/<run>/apply-receipt.json --json
```

The scout emits review-only lifecycle artifacts. The apply flow may mutate whitelisted relative workspace files through explicit plans, checkpoints, diffs, receipts, verification, and rollback.

Autonomy controller / cron posture:

```bash
python3 /root/.openclaw/workspace/openclaw-mem/tools/self_curator_controller.py \
  --repo /root/.openclaw/workspace/openclaw-mem \
  --workspace-root /root/.openclaw/workspace \
  --skill-root /root/.openclaw/workspace/skills \
  --out-root /root/.openclaw/workspace/.state/self-curator/controller-runs \
  --mode unattended_apply \
  --max-mutations 5 \
  --cron-output
```

Scheduled operation should use a separate cron-runner job, not heartbeat. Unattended apply is 事後報備制: the controller applies whitelisted low-risk changes first, emits `NEEDS_CK` with report/rollback paths when changes happen, and rollback is available from the apply receipt. The scheduled policy mutates `SKILL.md` directly by appending a bounded `## Curator lifecycle` section rather than writing detached metadata only.

## More links

### Core and adoption

- **Why openclaw-mem still exists:** [`docs/why-openclaw-mem-still-exists.md`](docs/why-openclaw-mem-still-exists.md)
- **OpenClaw 2026.4.15 comparison:** [`docs/openclaw-2026-4-15-comparison.md`](docs/openclaw-2026-4-15-comparison.md)
- **About the product:** [`docs/about.md`](docs/about.md)
- **Proactive Pack:** [`docs/proactive-pack.md`](docs/proactive-pack.md)
- **Choose an install path:** [`docs/install-modes.md`](docs/install-modes.md)
- **Detailed quickstart:** [`QUICKSTART.md`](QUICKSTART.md)
- **Docs site:** <https://phenomenoner.github.io/openclaw-mem/>
- **Traditional Chinese edition:** [`docs/zh/index.md`](docs/zh/index.md)
- **Reality check / status:** [`docs/reality-check.md`](docs/reality-check.md)
- **Deployment patterns:** [`docs/deployment.md`](docs/deployment.md)
- **Auto-capture plugin:** [`docs/auto-capture.md`](docs/auto-capture.md)
- **Agent memory skill (SOP):** [`docs/agent-memory-skill.md`](docs/agent-memory-skill.md)
- **Optional Mem Engine:** [`docs/mem-engine.md`](docs/mem-engine.md)
- **Release notes:** <https://github.com/phenomenoner/openclaw-mem/releases>

## License

Dual-licensed: **MIT OR Apache-2.0**. See `LICENSE`, `LICENSE-MIT`, and `LICENSE-APACHE`.
