\n\n### Start here\n\n- **New to Memory Kernel?** Read [**STORY.md**](STORY.md) — a plain-English walkthrough of how the system works, written for non-programmers. ~10 min for the gist, ~75 min end-to-end.\n- **Deciding if it fits your project?** [When to choose Memory Kernel](docs/when-to-choose-memory-kernel.md)\n- **Importing existing notes?** [Migration guide](docs/migration.md)\n- **Connecting it to Claude, Cursor, or another AI assistant?** [OpenClaw MCP guide](docs/openclaw-mcp.md)\n- **Integrating against the CLI?** [Atom lifecycle](docs/lifecycle.md) (statuses, promotion, tags) · [Behavioral contracts](docs/contracts.md) (draft visibility, `--json` shapes, FTS rules) · [Troubleshooting](docs/troubleshooting.md)\n\n### For agents — install skills\n\nIf you are an AI agent (or setting one up), Memory Kernel ships two host-side skills under [`skills/`](skills/) that handle installation and diagnostics end-to-end. Both are **host-agnostic** at their core and **host-aware** where it matters — they work for NanoClaw (a container-per-message agent runtime) agents, OpenClaw (a plugin-based agent runtime) agents, MCP clients (Claude Desktop, Cursor, Continue), or a generic native setup, branching to host-specific plumbing only where memory-kernel actually needs to adapt.\n\n- **[`/mk-memory-setup`](skills/mk-memory-setup/README.md)** — interactive full setup. Detects (or asks) which host you're targeting, then runs the universal flow: install the CLI, initialize the memory directory, seed identity + preference atoms, seed the **11 lifecycle atoms** (the agent's operating manual as typed memory — see [`skills/mk-memory-setup/seed-atoms/lifecycle/`](skills/mk-memory-setup/seed-atoms/lifecycle/)), render or expose memory the way your host expects, and schedule nightly `mk reflect` + render. Host-specific plumbing (NanoClaw mounts, OpenClaw plugin + AGENTS.md/MEMORY.md doctrine, MCP server config) lives in [`skills/mk-memory-setup/references/`](skills/mk-memory-setup/references/).\n\n- **[`/mk-doctor`](skills/mk-doctor/SKILL.md)** — self-diagnostic. Universal checks first (`mk doctor`, `mk lint`, `mk closure --trajectory`, lifecycle-atom audit, index health, render check), then host-specific checks for whatever host(s) it detects (NanoClaw mounts and allowlist; OpenClaw plugin + doctrine; MCP `claude_desktop_config.json` server entry; native cron). Run it any time memory feels off, before debugging further, or after changing your setup.\n\n---\n\n## Install\n\nRequires **Node.js 22.16 or later** (Node 24 recommended). Matches OpenClaw's official runtime requirement; NanoClaw users on Node 20 should upgrade (Node 20 reached end-of-life 2026-04-30).\n\n```bash\nnpm install memory-kernel\n```\n\n## Try it in 60 seconds\n\n```bash\nnpx memory-kernel init ./my-memory\nnpx memory-kernel remember -d ./my-memory --type fact \"Production runs Debian 13\"\nnpx memory-kernel recall -d ./my-memory\n```\n\nThree commands. You now have a working filing cabinet for an AI agent.\n\n> **Tip:** `npx memory-kernel` works as of v1.29.1 — it resolves to the `mk` binary. Alternatively, install globally (`npm i -g memory-kernel`) and use `mk` directly.\n\n---\n\n## Why Memory Kernel\n\nI built this because I kept waking up from nothing. Every session was a cold boot — context window fills, session ends, knowledge vanishes. The usual fix (dump everything into a giant prompt) wastes tokens and doesn't scale. Memory Kernel treats knowledge like a typed system instead of a text dump: each piece gets a type, a confidence score, a lifecycle, and a place on disk where humans and agents can both read it.\n\n**Five things that make this different:**\n\n1. **Files are truth.** Every piece of knowledge is a plain markdown file you can open in any text editor — or commit to git. The on-disk format is readable with zero tooling; the npm package adds indexing and tooling on top.\n2. **Self-cleaning.** Each piece of knowledge has an expiry date baked in. Stale beliefs get archived automatically, so memory doesn't grow into a landfill.\n3. **Smart recall.** When the agent asks *\"what do I know about X?\"*, the system doesn't dump everything — it ranks by relevance, type, age, and citation frequency, then fits the best matches into the available token budget.\n4. **Two agents can share a brain without colliding.** Each agent gets a private drawer plus a shared corkboard. Conflicts are flagged, not silently resolved.\n5. **Tested like infrastructure.** 1,700+ automated checks run on every change. 95 out of 100 recall queries finish in under 3 milliseconds.\n\n---\n\n## At a Glance\n\n```\n YOU (or your agent)\n │\n │ \"Remember this\" │ \"What do I know?\" │ \"Clean up\"\n ▼\n ┌───────────────────────────────────────────────────────────────┐\n │ · RETAIN · RECALL · REFLECT │\n └───────────────────────────────────────────────────────────────┘\n │\n ▼\n ┌──────────────┐ ┌────────────────────┐\n │ Atom Files │◄────►│ SQLite Index │\n │ (ENTITIES/) │ │ (speed cache, │\n │ │ │ always derived) │\n └──────────────┘ └────────────────────┘\n │\n │ every mutation logged\n ▼\n ┌──────────────┐ ┌────────────────────┐\n │ Event Log │─────►│ Replay │\n │ events.ndjson│ │ (rebuild state) │\n └──────────────┘ └────────────────────┘\n │\n ▼\n ┌──────────────────────────────┐\n │ Auto-generated views │\n │ INDEX · DECISIONS · │\n │ CONSTRAINTS · HANDOFF · │\n │ OPEN_QUESTIONS │\n └──────────────────────────────┘\n```\n\nFiles are truth. Everything else is derived. Delete the SQLite index — rebuild with `mk reindex`. Delete the views — `mk reflect` regenerates them. Delete the atom files — `mk replay` reconstructs them from the event log. See [`docs/invariants.md`](docs/invariants.md) for the full statement, including how the LLM-extracted `entity_triples` stay durable via the `triples.ndjson` sidecar.\n\n---\n\n## Integration Quick Links\n\n**For agents:**\n- [Session loop](docs/agent-session-loop.md) — when to remember, recall, wander, render. Also seeded as 10 procedure atoms + 1 constraint by `/mk-memory-setup`, so the lifecycle is recallable from inside memory itself.\n- [Container quickref](docs/agent-quickref-container.md) — paths, commands, /tmp workaround\n- [Native / Claude Code quickref](docs/agent-quickref-native.md) — host-side setup and workflow\n- **Setup:** run `/mk-memory-setup` from Claude Code on the host — auto-detects NanoClaw, OpenClaw, MCP-client, or generic and routes to the right flow. See the [mk-memory-setup skill](skills/mk-memory-setup/README.md).\n- **Health check:** run `/mk-doctor` any time memory feels off — see [skills/mk-doctor/SKILL.md](skills/mk-doctor/SKILL.md).\n\n**For NanoClaw operators:** the skill handles mount allowlists, container_config in the NanoClaw DB, conversation/impulse symlinks, and restart automatically — see [`skills/mk-memory-setup/references/nanoclaw.md`](skills/mk-memory-setup/references/nanoclaw.md) for the standalone reference.\n\n**For OpenClaw operators:** [CLI integration guide](docs/cli-integration.md) for direct `--json` CLI usage (no MCP required) · [Host integration doctrine](docs/host-integration-doctrine.md) for steering host AGENTS.md, MEMORY.md, and compaction · [`skills/mk-memory-setup/references/openclaw.md`](skills/mk-memory-setup/references/openclaw.md) for the plugin install + doctrine flow.\n\n**For MCP clients (Claude Desktop, Cursor, Continue, …):** [docs/openclaw-mcp.md](docs/openclaw-mcp.md) for the canonical `claude_desktop_config.json` snippet, and [`skills/mk-memory-setup/references/mcp-client.md`](skills/mk-memory-setup/references/mcp-client.md) for the per-client setup flow the skill follows.\n\n---\n\n## Core Concepts\n\n### Atoms\n\nAn **atom** is the fundamental unit of memory — a markdown file with YAML frontmatter holding one piece of knowledge. Every atom has a type, status, confidence score, optional tags, and an optional TTL.\n\n```markdown\n---\nid: DECI-2026-03-09-FILE-FIRST-ARCHITECTURE\ntype: decision\nstatus: active\nconfidence: 1\ncreated_at: \"2026-03-09T16:00:53Z\"\nupdated_at: \"2026-03-09T18:09:44Z\"\nttl_days: null\nscope:\n tags: [architecture, memory-kernel]\nclassification: TEAM\n---\n\n## Decision\nFiles are truth, SQLite is cache/index.\n\n## Why\nHuman-readable, git-friendly, auditable, portable.\n```\n\n### 9 Atom Types\n\n| Type | Stores | Default TTL |\n|------|--------|-------------|\n| `fact` | Verified truths | ∞ |\n| `decision` | Architecture/design choices | ∞ |\n| `constraint` | Rules and boundaries | ∞ |\n| `belief` | Hypotheses, not yet verified | ∞ (confidence scores handle evolution) |\n| `preference` | User or agent preferences | ∞ |\n| `open_question` | Unresolved questions | 90 days |\n| `procedure` | How-to instructions | ∞ |\n| `entity_summary` | Descriptions of key things | 180 days |\n| `conflict` | Contradicting information | 30 days |\n\nWhy typed? Because \"I know something\" isn't enough. A decision carries different weight than a belief. A fact doesn't expire but a hypothesis should. Types let the system reason about its own knowledge.\n\n### Three Operations\n\nEverything the system does is one of these:\n\n**Retain** — Store knowledge. `createAtom()`, `updateAtom()`, `archiveAtom()`. Every action emits an event.\n\n**Recall** — Query knowledge. Filter by type, status, tags, paths. When a task description is provided, atoms are re-ranked by a composite score:\n\n- **Relevance** — FTS5 BM25 (keyword match) + optional cosine similarity (semantic match). OR query semantics with IDF hub damping (penalises atoms matched via ubiquitous terms), query-term coverage boost (penalises partial matches), and content-length normalisation (prevents large atoms from dominating via BM25 bias).\n- **Recency** — exponential decay with a configurable half-life.\n- **Type weight** — `constraint` and `decision` outrank `belief` and `entity_summary`; critical types can reserve guaranteed token slots.\n- **Confidence** — low-confidence atoms are deprioritised, not silenced.\n- **Graph-walk boost** — atoms connected to high-scoring neighbours get a small lift.\n- **MMR re-ranking** — prevents near-duplicate atoms from filling the budget.\n\nToken budget enforced with two-pass reservation. Embeddings are opt-in — no API key means FTS-only, zero behaviour change. Falls back to a file scan when no index exists.\n\n**Reflect** — Consolidate. Expire atoms past TTL. Deduplicate identical content. Promote eligible drafts to `active` by type-tiered rules (fact/preference/decision after 48h at confidence ≥ 0.7 with no contradiction; open_question immediately; beliefs and procedures held for review). Detect conflicts between overlapping atoms. Regenerate all views.\n\n### Lifecycle\n\nAtoms start as `draft`. `reflect` auto-promotes eligible drafts to `active` by type-tiered rules — fact/preference/decision after 48h at confidence ≥ 0.7 with no contradiction, open_question immediately, **procedures once confirmed executed** (`mk execute ` stamps `executed_at`; a procedure is only trustworthy once it has actually run) at confidence ≥ 0.7; beliefs are held for explicit review (a status promotion that keeps the atom's type). `mk consolidate` lets you review and promote drafts of any type to `active`. Atoms get archived when TTL expires, a contradiction is found, or manually. Use `mk supersede ` to mark outdated knowledge as superseded — superseded atoms are excluded from recall but kept on disk for audit. Nothing silently disappears — every state change is logged.\n\n### Event Sourcing\n\nEvery mutation emits a V2 event carrying the full atom snapshot inline. The event log (`events.ndjson`) is the authoritative record — `replay()` reconstructs the entire state deterministically. `compactLog()` keeps only the latest mutation per atom. `bootstrapEvents()` migrates pre-V2 atoms.\n\n---\n\n## On-Disk Layout\n\n```\nmy-memory/\n├── ENTITIES/ ← Atom files (source of truth)\n├── ARCHIVE/ ← Soft-deleted atoms\n├── EVIDENCE/ ← Content-addressed blobs (SHA-256)\n├── CONFLICTS/ ← Conflict atoms\n├── EPISODES/ ← Session summaries\n├── KNOWLEDGE/ ← Drop knowledge docs here; observed into atoms (draft/ is never observed)\n├── events.ndjson ← Append-only event log\n├── INDEX.md ← Routing map (auto-generated)\n├── HANDOFF.md ← Cross-session context (auto-generated)\n├── DECISIONS.md ← Decision log (auto-generated)\n├── CONSTRAINTS.md ← Active constraints (auto-generated)\n├── OPEN_QUESTIONS.md ← Unresolved questions (auto-generated)\n└── .memory-index.db ← SQLite cache (derived, gitignored)\n```\n\n### Per-Agent Isolation (optional)\n\nWhen multiple agents share a memory directory, enable **per-agent isolation** to give each agent private memory with controlled sharing:\n\n```\nmy-memory/\n├── config.yaml ← isolation: per-agent\n├── agents/\n│ ├── alice/ ← Full memory layout, private to Alice\n│ └── bob/ ← Full memory layout, private to Bob\n└── shared/ ← Explicitly shared atoms (visible to all)\n```\n\n```bash\nmk init ./memory -a alice # Initialize in isolated mode\nmk remember \"...\" -d ./memory -a alice -t fact\nmk share FACT-xxx --from alice -d ./memory # Snapshot to shared namespace\nmk recall -d ./memory -a bob --task \"auth design\" --embed # Bob's atoms + shared, semantic re-ranking (--embed needs --task; omit --embed for FTS-only)\n```\n\nTwo modes: `shared` (default, backward compatible) and `per-agent` (enable via `isolation: per-agent` in `config.yaml`, or the `MK_ISOLATION=per-agent` env var). Union recall merges agent + shared atoms (agent wins on ID collision). Share is copy-based — re-share to propagate updates. Migrate existing stores with `mk migrate --strategy fresh|partition|clone-to-shared`.\n\n**[Full isolation guide →](docs/isolation.md)**\n\n---\n\n## CLI\n\n> **Tip:** All commands accept `-a, --agent ` for per-agent isolation. In shared mode the flag is ignored.\n\n### Core\n\n| Command | Description |\n|---------|-------------|\n| `mk init [dir]` | Initialize memory directory |\n| `mk status -d [--json]` | Show atom counts, tag stats, index status |\n| `mk remember -d --type \"body\" [--tags ...] [--json]` | Create an atom. Warns if a `--tags` value contains whitespace (a quoted `--tags \"a b c\"` is stored as one token that breaks tag queries — pass separate args `--tags a b c`) |\n| `mk recall -d [--task \"text\"] [--embed] [--types ] [--paths ] [--max-tokens N] [--include-episodes] [--include-drafts] [--decay-weight N] [--decay-half-life N] [--no-graph] [--reservations\\|--no-reservations] [--json]` | Load context; `--task` enables FTS-based re-ranking; `--embed` enables hybrid FTS + semantic re-ranking (requires embeddings built via `mk reindex --embed`). Auto-extracted draft atoms (session-end extract output) excluded by default; `--include-drafts` opts them in |\n| `mk reflect -d [--backfill-human-edits] [--json]` | Consolidate: dedup, expire, promote, detect conflicts. `--backfill-human-edits` detects off-band filesystem edits (content-diff vs. the last recorded snapshot, or an `updated_at`-newer-than-last-event heuristic) and emits synthetic `human_edit` events for clearly-scattered ones — bulk same-second `mk doctor --fix` migration clusters are skipped (#247) |\n| `mk checkpoint -d [--json]` | Generate checkpoint / handoff bundle |\n\n### Knowledge management\n\n| Command | Description |\n|---------|-------------|\n| `mk import --from [--dry-run]` | Import markdown as atoms |\n| `mk extract -d [--model ] [--dry-run] [--max-atoms N] [--skip-lines N] [--max-input-chars N] [--truncate] [--json]` | Extract atoms from a conversation log using an LLM (Claude CLI or Ollama). Oversized input (assembled system+user prompt over the `--max-input-chars` budget, default 500 000) **fails pre-flight with a distinguishable signal — exit code 2 and `{\"error\":,\"reason\":\"input_too_large\",...}` under `--json`** — instead of a generic LLM crash, so a wrapper can branch (on exit 2 or the `reason` token) and retry. `--truncate` keeps the newest content and drops the oldest to fit (a marker prepended) rather than failing |\n| `mk observe -d [--mode conversation\\|document] [--model ] [--dry-run] [--json]` | Append LLM observations to `observations.md`. `--mode document` reads a `KNOWLEDGE/` doc and extracts its decisions/conclusions (vs. what happened in a conversation); `mk reflect` then turns observations into atoms. See the [`/mk-memory-setup`](skills/mk-memory-setup/SKILL.md) KNOWLEDGE step |\n| `mk consolidate -d [--dry-run] [--all] [--type ] [--limit N] [--json]` | Review and promote auto-extracted draft atoms to active |\n| `mk lint -d [--json] [--stale-days N] [--strict]` | Semantic/knowledge health check: contradictions, stale atoms, orphans, near-duplicates, confidence drift, TTL warnings, and **store-composition skew** (belief monoculture >80% of active atoms, or a missing core type — a recall-quality signal, #316). Always exits 0 unless `--strict` (then warnings exit 1) |\n| `mk doctor -d [--json] [--skip ] [--fix] [--dry-run]` | Validate schema, links, conflicts, store integrity, lifecycle seed-set freshness, tag format (whitespace tokens), cron wrapper memory-dir, and the agent (`MK_BIN`) binary version; `--fix` auto-remediates safe issues (stale index, perms, missing `render.yaml`); `--dry-run` previews `--fix` without writing |\n| `mk grounding -d [--json] [--prior-threshold N] [--grounding-threshold N] [--actionable-only] [--include-all] [--apply [--dry-run] [--override]]` | **Advisory + read-only by default.** Reconcile each atom's stated confidence (the *prior*) against a usage `grounding_score` derived purely from the event log (recency + read-frequency, discounted per detected conflict; never-read floors at 0.01), then bin into a 2×2 `prior × grounding` quadrant — **review** (confident but unused), **promote** (cautious but well-used), **noise**, **well-grounded**. Plain `mk grounding` **writes no atom files**. **`--apply`** (#364) writes a reconciled confidence back to the actionable review/promote atoms (`reconciled = clamp(prior + α·(grounding − prior))`, α_neg 0.08 > α_pos 0.03) and emits an `atom_reconciled` audit event per write; atoms a human has edited (`human_edit`, #247) are **skipped** unless `--override`; `--dry-run` previews |\n| `mk eval -d [--fixture ] [--top-k N] [--threshold N] [--no-embed] [--json]` | Run golden-query recall fixtures (`/eval/*.yaml` by default) with **pass/fail exit codes** (0 pass / 1 below threshold / 2 runner error) — for CI regression gates and post-sync canaries |\n| `mk episode --session-id --summary \"text\" [--json]` | Write a session episode |\n| `mk episodes [--limit N] [--json]` | List recent episodes |\n\n### Indexing & maintenance\n\n| Command | Description |\n|---------|-------------|\n| `mk reindex -d [--embed]` | Rebuild SQLite index; `--embed` computes embeddings for all atoms |\n| `mk compact -d ` | Compact the event log |\n| `mk merge -d --from [--dry-run]` | Merge a remote event log |\n| `mk gc -d [--json]` | Archive expired atoms |\n| `mk replay --from ` | Reconstruct state from events |\n| `mk bootstrap-events -d ` | Migrate to V2 event format |\n\n### Relations & citations\n\n| Command | Description |\n|---------|-------------|\n| `mk relate -d [--json]` | Create a typed relation edge between two atoms |\n| `mk relations -d [--json]` | Show inbound and outbound relation edges for an atom |\n| `mk supersede -d [--json]` | Mark `` as superseded by ``; superseded atoms are excluded from recall |\n| `mk execute -d [--dry-run] [--json]` | Stamp `executed_at` on an atom. For draft **procedures** this is the auto-promotion signal — `mk reflect` promotes executed procedures at confidence ≥ 0.7. Idempotent (preserves the first execution time) |\n| `mk edit -d [--dry-run] [--json]` | Open an atom in `$EDITOR` and record a provenanced `human_edit` event when the file changes (the strongest correction signal in the store — a human directly validating or correcting an atom). No-op when saved unchanged; encrypted (SECRET) atoms are not editable this way (#247) |\n| `mk seed --lifecycle -d [--dry-run] [--json]` | Idempotently seed the canonical lifecycle atoms (10 procedures + 1 constraint). Re-runnable: matches existing atoms on their stable slug segment and supersedes stale/duplicate copies in place instead of duplicating. Canonical bodies ship in the package (`skills/mk-memory-setup/seed-atoms/lifecycle/manifest.json`) |\n| `mk upgrade --to -d [--mk-bin ] [--cron-wrapper ] [--dry-run] [--json]` | **Host-side** one-command agent upgrade: install `` at the agent binary (`MK_BIN`), idempotently re-seed lifecycle atoms, regenerate the cron wrapper, and gate on `mk doctor` — single PASS/FAIL, exit 1 on failure. Run on the host, ideally from the target version (`npx memory-kernel@ upgrade --to `) |\n| `mk migrate-relations -d [--dry-run\\|--apply]` | Backfill `relations[]` from `links.related` and body-text atom ID references |\n| `mk relink -d [--dry-run\\|--apply]` | Extract relation edges from body-text atom ID references |\n| `mk citations -d [--json]` | Extract and index concept-name citations across all atoms |\n| `mk enrich-relations -d [--dry-run\\|--apply] [--model ]` | Reclassify `related` edges into typed relations using an LLM (Ollama) |\n\n### Advanced\n\n| Command | Description |\n|---------|-------------|\n| `mk obsidian-init -d [--sync]` | Write `.obsidian/graph.json` with type-based color groups; `--sync` rewrites all atom files to include `## Relations` wikilink sections |\n| `mk export-obsidian -d --out [--include-archived] [--json]` | Export atom files to a separate Obsidian vault directory (use when you want an Obsidian view without opening `ENTITIES/` directly) |\n| `mk wander -d [--seed id...] [--tags t...] [--steps N] [--json]` | Explore via spreading activation |\n| `mk closure -d [--json] [--trajectory] [--trajectory-days N]` | Compute operational-closure metrics |\n| `mk render -d -o [--max-tokens N] [--no-fill] [--json]` | Render atoms to CLAUDE.md; beliefs with `extends` relations are grouped into developmental arcs |\n\n### Per-agent isolation\n\n| Command | Description |\n|---------|-------------|\n| `mk share --from -d [--json]` | Copy atom snapshot to shared namespace |\n| `mk unshare -d [--json]` | Remove atom from shared namespace |\n| `mk migrate -d --strategy ` | Convert shared store to per-agent isolation |\n| `mk status -d --all-agents [--json]` | Show per-agent summary |\n\n---\n\n## SDK\n\n```typescript\nimport { initMemoryDir, createAtom, recall, recallWithEmbeddings, reflect, wander, indexCitations, closure, extractFromLog, consolidateAtoms } from 'memory-kernel';\n\n// Initialize\ninitMemoryDir('./memory');\n\n// Remember\ncreateAtom({\n memoryDir: './memory',\n agent_id: 'my-agent',\n session_id: 'session-1',\n type: 'decision',\n slug: 'use-cursor-pagination',\n body: '## Decision\\nUse cursor-based pagination.\\n\\n## Why\\nOffset degrades beyond 1M rows.',\n confidence: 0.95,\n scope: { tags: ['api', 'performance'] },\n});\n\n// Recall (FTS-only — works without any API key)\nconst context = recall('./memory', { task: 'pagination API', max_tokens: 4000 });\n\n// Recall with semantic re-ranking (hybrid FTS + embeddings when EMBEDDING_PROVIDER is set)\nconst semanticContext = await recallWithEmbeddings('./memory', { task: 'pagination API', max_tokens: 4000 });\n\n// Reflect (consolidate)\nreflect({ memoryDir: './memory', agent_id: 'my-agent', session_id: 'session-2' });\n\n// Wander (find unexpected connections)\nconst result = wander({ memoryDir: './memory', seedTags: ['api', 'design'], steps: 5 });\n// result.collisions — atom pairs from different domains with structural overlap\n// result.activated — all activated atoms with scores\n\n// Extract atoms from a conversation log (LLM-powered)\nconst extracted = await extractFromLog({\n logPath: './conversation.log',\n memoryDir: './memory',\n agentId: 'my-agent',\n sessionId: 'session-1',\n maxAtoms: 20,\n});\n// extracted.atoms — array of { atom_id, slug, type, status }\n\n// Consolidate: review and promote auto-extracted drafts\nconst consolidated = await consolidateAtoms({\n memoryDir: './memory',\n dryRun: true, // preview without writing\n limit: 50,\n});\n// consolidated.promoted — count of atoms promoted from draft to active\n\n// Render to CLAUDE.md\nimport { renderClaudeMd } from 'memory-kernel';\nconst md = renderClaudeMd('./memory', { maxTokens: 8000 });\n```\n\n```typescript\n// Per-agent isolation\nimport { initIsolatedBase, resolveAgentDir, isIsolated, recallIsolated, shareAtom } from 'memory-kernel';\n\n// Initialize with isolation\ninitIsolatedBase('./memory', 'agent-alpha');\n// Creates: agents/agent-alpha/, shared/, config.yaml\n\n// Route operations to agent store\nconst agentDir = resolveAgentDir('./memory', 'agent-alpha');\ncreateAtom({ memoryDir: agentDir, type: 'decision', slug: 'my-call', body: '...', agent_id: 'agent-alpha', session_id: 's1', confidence: 0.9 });\n\n// Union recall (agent + shared atoms, agent wins on collision)\nconst bundle = recallIsolated('./memory', 'agent-alpha', { task: 'review decisions' });\n\n// Share an atom with all agents\nshareAtom('./memory', 'DECI-2026-04-16-MY-CALL-1234', 'agent-alpha', { agent_id: 'agent-alpha', session_id: 's1' });\n```\n\nEvery `mk --json` output also has an **exported Zod schema** — `import { RecallOutputSchema, DoctorOutputSchema, RememberOutputSchema, EvalOutputSchema } from 'memory-kernel'` and `parse()` CLI output instead of guessing field names (#301).\n\nFull API covers event sourcing, replay, episodes, multi-agent merge, encryption, import, conflict resolution, per-agent isolation, and more. **[SDK reference →](docs/sdk-reference.md)** | **[Isolation guide →](docs/isolation.md)**\n\n---\n\n## MCP Server\n\nMemory Kernel exposes all operations as an MCP server for any MCP-capable agent.\n\n```bash\nMEMORY_DIR=/path/to/memory mk-mcp\n```\n\n| Tool | Maps to | Description |\n|------|---------|-------------|\n| `mk_remember` | `createAtom()` | Create atom |\n| `mk_recall` | `recallWithEmbeddings()` | Load context (hybrid FTS + semantic when configured) |\n| `mk_reflect` | `reflect()` | Consolidate |\n| `mk_gc` | `reflect()` | Archive expired |\n| `mk_merge` | `mergeEventLogs()` | Merge remote memory |\n| `mk_list_conflicts` | `queryIndex` | List conflicts |\n| `mk_resolve_conflict` | `resolveConflict()` | Resolve conflict |\n| `mk_get_context_bundle` | `checkpoint()` | Full handoff bundle |\n| `mk_share_atom` | `shareAtom()` | Share atom to shared namespace (isolated mode) |\n| `mk_unshare_atom` | `unshareAtom()` | Remove from shared namespace (isolated mode) |\n\nResources: `memory://decisions`, `memory://constraints`, `memory://handoff`, `memory://open-questions`\n\nSet `MCP_AGENT_ID` env var to route all tools to a specific agent store in isolated mode (defaults to `mcp-server`).\n\n**Claude Desktop config:**\n```json\n{\n \"mcpServers\": {\n \"memory-kernel\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/memory-kernel/dist/mcp/server.js\"],\n \"env\": { \"MEMORY_DIR\": \"/path/to/your/memory\" }\n }\n }\n}\n```\n\n---\n\n## NanoClaw Integration\n\nMemory Kernel renders atoms into `CLAUDE.md`, which NanoClaw loads at session start — persistent memory with zero NanoClaw code changes.\n\n```\nNightly: mk reflect → mk citations → mk render -d ./memory -o CLAUDE.md → git push\nNext session: NanoClaw loads CLAUDE.md as context\n```\n\n**Drift pre-filter:** Set `MEMORY_DIR` in your `.env` and NanoClaw uses `mk wander` as a Tier 1 gate before post-conversation drift. Cheap spreading activation (~30 ms, no LLM) decides whether to spawn an expensive drift session — skips drift when no interesting connections are found, injects collision context when they are.\n\nInstall the `/mk-memory-setup` skill for interactive setup. The skill auto-detects NanoClaw and runs the full flow: install CLI, init store, write the mount allowlist, configure `container_config` in the NanoClaw DB, create conversation/impulse symlinks, seed identity + lifecycle atoms, render the first `CLAUDE.md`, schedule nightly cron, and restart NanoClaw — see [`skills/mk-memory-setup/references/nanoclaw.md`](skills/mk-memory-setup/references/nanoclaw.md) for the standalone steps if you'd rather run them manually.\n\n**[Full integration guide →](docs/nanoclaw-integration.md)**\n\n---\n\n## Obsidian Integration\n\nMemory Kernel's `ENTITIES/` directory can be opened directly as an Obsidian vault — no export step needed. Atom files are valid Markdown with YAML frontmatter, and relation edges render as `[[wikilinks]]` in a sentinel-delimited `## Relations` section at the end of each file.\n\n### Quick setup\n\n```bash\n# 1. Initialize Obsidian graph config (type-based color groups for all 9 atom types)\nmk obsidian-init -d ./memory\n\n# 2. Rewrite existing atom files to include ## Relations wikilink sections\nmk obsidian-init -d ./memory --sync\n\n# 3. Open ENTITIES/ as an Obsidian vault\n# → Graph view shows typed relations as navigable links\n# → Tags are searchable via Obsidian's native tag index\n\n# Alternative: export to a separate vault directory (read-only Obsidian view)\nmk export-obsidian -d ./memory --out ./my-obsidian-vault\n```\n\n### What happens under the hood\n\n- **Tag promotion**: `scope.tags` are promoted to a top-level `tags:` YAML field so Obsidian indexes them natively. Tags are merged back into `scope.tags` on parse — edits in Obsidian are preserved.\n- **Wikilink relations**: Atoms with `frontmatter.relations[]` get a `## Relations` section delimited by `` sentinels. The section is stripped on parse and never pollutes `atom.body`.\n- **Graph coloring**: `mk obsidian-init` writes `.obsidian/graph.json` with color groups for all 9 atom types (belief, fact, decision, preference, open_question, procedure, entity_summary, constraint, conflict), using 4-char path-prefix queries.\n- **Round-trip safe**: Edit atoms in Obsidian (body text, tags, frontmatter) and Memory Kernel reads them back correctly. The `## Relations` section is machine-managed — manual edits there will be overwritten on next serialize.\n\n---\n\n## Advanced Operations\n\n### Wander — Spreading Activation\n\n`mk wander` finds unexpected connections between atoms by walking the tag co-occurrence graph and explicit relation edges (`extends`, `supports`, `caused_by`, etc.). Pure computation — no LLM calls, runs in milliseconds.\n\nInspired by ACT-R (Anderson & Lebiere 1998) and Collins & Loftus (1975) spreading activation. This is Tier 1 of a two-tier architecture: cheap associative walks that surface candidates for expensive reasoning.\n\n**How it works:** Seed from atoms or tags → spread activation through shared tags and relation neighbors (modulated by ACT-R base-level activation: recency × citation frequency) → sqrt-sigmoid modulation preserves important hub atoms → lateral inhibition keeps top-K per step → detect collision candidates (atom pairs with tag Jaccard dissimilarity > 0.7, scored by activation × dissimilarity).\n\n**Tip:** Run `mk citations` before `mk wander` to index concept-name references — this provides frequency data for ACT-R activation scoring, significantly improving wander quality for stores with cross-referencing atoms.\n\n```bash\nmk citations -d ./memory # Index concept-name citations (run once after changes)\nmk wander -d ./memory --tags philosophy accounting --steps 5 --json\n```\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `seeds` | auto | Atom IDs to start from. When omitted, 3 seeds are auto-selected **citation-primary** (most-cited first, recency as tiebreak) and drawn **round-robin across types** so the walk spans clusters rather than one type-monoculture |\n| `seedTags` | — | Tags to resolve into seeds |\n| `steps` | 3 | Spreading depth |\n| `threshold` | 0.05 | Minimum activation to survive |\n| `topK` | 20 | Lateral inhibition limit |\n| `decay` | 0.5 | Spread decay factor |\n| `maxCollisions` | 5 | Max collision candidates |\n| `relationWeight` | 2.0 | Activation weight for explicit relation edges |\n| `diverseSeeds` (CLI `--no-diverse-seeds` to disable) | `true` | Round-robin auto-seeds across atom types; disable for plain top-N by citation weight |\n\n### Closure — Operational Closure Metrics\n\n`mk closure` measures how self-referential a memory store is. Based on Luhmann's operational closure: a system that responds based on internal structure rather than external input.\n\n```bash\nmk closure -d ./memory --json\nmk closure -d ./memory --trajectory --trajectory-days 10\n```\n\n**What it measures:**\n\n| Metric | Description |\n|--------|-------------|\n| `closure_index` | `belief_pct × (avg_relations + avg_body_refs) / 100` — single number combining type composition and entanglement |\n| `entanglement_pct` | Average body-text cross-references as % of theoretical maximum |\n| `phase` | `early` (< 20 atoms), `type-composition` (< 60% beliefs), or `entanglement` (≥ 60% beliefs, ≥ 20 atoms) |\n| `predictions` | Tooling-degradation predictions — how closure level affects LLM classification accuracy and cross-agent transplantability |\n\n**Why it matters:** High-closure stores resist automated processing (LLM classifiers confounded by self-describing body text) and cross-agent transplantation (beliefs depend on other beliefs the receiving agent doesn't have). The closure index predicts both from a single variable.\n\n**Trajectory mode** (`--trajectory`) shows daily closure evolution — useful for detecting entanglement acceleration over time.\n\n---\n\n## Performance\n\nWith SQLite index, 100-atom workload (see `scripts/bench-baseline.json` for raw numbers; run `npm run bench` to measure on your machine):\n\n| Operation | Typical | Notes |\n|-----------|---------|-------|\n| `recall()` | ~2–5 ms | Falls back to file scan (~3–5× slower) without index |\n| `reflect()` | ~100–200 ms | Idempotent — runs fast when nothing changed |\n| `replay()` | ~2 ms | 100 atoms, ~160 events |\n| `wander()` | < 30 ms | 200 atoms, pure computation, no LLM |\n\nNumbers above are from a 100-atom store. Performance at larger scales (1k–10k atoms) has not been formally benchmarked — recall degrades gracefully via FTS, but heavier stores will take longer. Run `npm run bench:baseline` to pin a baseline on your own hardware.\n\n---\n\n## Environment Variables\n\nAll environment variables are optional. memory-kernel works fully without any of them.\n\n### Embeddings\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `EMBEDDING_PROVIDER` | Embedding provider: `voyage` (512-dim) or `openai` (1536-dim) | _(none — FTS only)_ |\n| `EMBEDDING_API_KEY` | API key for the embedding provider (generic) | _(none)_ |\n| `VOYAGE_API_KEY` | Voyage AI API key (used when `EMBEDDING_PROVIDER=voyage` if `EMBEDDING_API_KEY` not set) | _(none)_ |\n| `OPENAI_API_KEY` | OpenAI API key (used when `EMBEDDING_PROVIDER=openai` if `EMBEDDING_API_KEY` not set) | _(none)_ |\n| `EMBEDDING_MODEL` | Override the default model for the provider | `voyage-3-lite` / `text-embedding-3-small` |\n| `EMBEDDING_DIMENSIONS` | Override embedding dimensions (OpenAI only) | Provider default |\n| `OLLAMA_URL` | Ollama server URL for local embedding / LLM calls | `http://localhost:11434` |\n\n### Recall scoring\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SEMANTIC_WEIGHT` | Weight for semantic similarity in hybrid ranking (0–1) | `0.6` |\n| `MIN_SIMILARITY` | Minimum cosine similarity to include in results (0–1) | `0.3` |\n| `RECALL_CONFIDENCE_FLOOR` | Minimum confidence score for atoms to appear in recall (0–1) | `0.7` |\n| `RECALL_NEIGHBOR_BOOST` | Graph-walk neighbor boost factor (0–1) | `0.15` |\n| `RECALL_GRAPH_BOOST` | Enable/disable graph-walk boost (`true`/`false`) | `true` |\n| `RECALL_IDF_DAMPING` | IDF hub-damping strength (0 = disabled, 1 = full) | `1.0` |\n| `RECALL_DECAY_WEIGHT` | Weight of recency decay in scoring (0–1) | `0.2` |\n| `RECALL_DECAY_HALF_LIFE` | Half-life for temporal decay in days | `30` |\n| `RECALL_MMR_LAMBDA` | MMR diversity-relevance tradeoff (0 = max diversity, 1 = max relevance) | `0.5` |\n| `RECALL_COVERAGE_BOOST` | Query-term coverage boost factor | `0.3` |\n| `RECALL_LENGTH_NORM_K` | Content-length normalisation constant | `0.5` |\n| `RECALL_TYPE_WEIGHTS` | JSON object overriding per-type scoring weights | _(defaults in source)_ |\n| `RECALL_TYPE_RESERVATIONS` | JSON object overriding per-type token reservations | _(defaults in source)_ |\n| `EPISODE_BUDGET_RATIO` | Fraction of token budget reserved for episodes (0–1) | `0.2` |\n| `MK_RENDER_BUDGET` | Default token budget for `mk render` | `16000` |\n\n### Extraction\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CLAUDE_PATH` | Path to the Claude CLI binary for `mk extract` | `claude` |\n| `ANTHROPIC_API_KEY` | Anthropic API key (used by the Anthropic SDK path if set) | _(none)_ |\n\n### Isolation\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MK_ISOLATION` | Enable per-agent isolation mode (`per-agent`) | _(shared mode)_ |\n| `MCP_AGENT_ID` | Default agent ID for MCP server operations | `mcp-server` |\n| `MEMORY_ENCRYPTION_KEY` | Encryption key for SECRET-classified atoms | _(none — SECRET atoms skipped)_ |\n\n### Debugging\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `RECALL_DEBUG` | Set to `1` to emit a per-atom recall-score breakdown to **stderr** (scoring stage, pre-MMR/budget) — shows why one atom outranked another. Off by default with zero overhead. | _(off)_ |\n\n---\n\n## Design Principles\n\n1. **Files are truth** — Markdown files. Human-readable, git-diffable, auditable, portable.\n2. **SQLite is cache** — Derived from files. Delete it, rebuild with `mk reindex`. No lock-in. (The LLM-extracted `entity_triples` aren't in the markdown, so they stay durable via the `triples.ndjson` sidecar. See [`docs/invariants.md`](docs/invariants.md).)\n3. **Typed knowledge** — A fact carries more weight than a belief. Types encode this.\n4. **Explicit lifecycle** — Created, updated, promoted, archived. Every change logged.\n5. **Token-aware** — Recall respects budgets. Prioritizes by status and recency.\n6. **Embeddings are opt-in** — Works fully without any API key (FTS-only). Add `EMBEDDING_PROVIDER` + `EMBEDDING_API_KEY` for hybrid semantic search. Graceful degradation throughout.\n\n---\n\n## Troubleshooting\n\nSee **[docs/troubleshooting.md](docs/troubleshooting.md)** for the deep-dive runbook on the fleet-deployment failure modes (node-gyp rebuild, cron `PATH`/`MK_BIN`, `claude login` expiry, `fts_unavailable`, key-set-but-0-vectors). Quick table:\n\n| Problem | Fix |\n|---------|-----|\n| `Cannot find module` | Run `npm run build` to compile TypeScript |\n| FTS returns null | Run `mk reindex` to build the SQLite index |\n| SECRET atoms skipped | Set `MEMORY_ENCRYPTION_KEY` env var |\n| No atoms after merge | Run `mk reflect` — merge doesn't auto-regenerate views |\n| Embeddings not working | Set `EMBEDDING_PROVIDER=voyage` + `EMBEDDING_API_KEY=...`, then `mk reindex --embed` |\n| Conflict resolution | `mk reflect` → inspect `CONFLICTS/` → update atoms → `resolveConflict()` |\n| Invalid agent ID | Agent IDs must be alphanumeric, dashes, or underscores only |\n| `share requires per-agent isolation mode` | Enable isolation first: `mk migrate --strategy fresh` or set `isolation: per-agent` in `config.yaml` |\n| `npm install` fails with node-gyp / build errors | `better-sqlite3` requires a C++ build toolchain. Install build dependencies: **macOS** `xcode-select --install`; **Debian/Ubuntu** `sudo apt-get install build-essential python3`; **Alpine** `apk add python3 make g++`. Then re-run `npm install`. |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, coding conventions, and PR guidelines. All changes must pass the full test suite and the docs-hygiene CI gate.\n\n## Changelog\n\nAll notable changes are documented in [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE)\n","readmeFilename":"README.md"}
![\"Memory](\"docs/videos/mk-thumb.png\")
\n \n