memkernel 0.3.0__tar.gz → 0.4.0__tar.gz

{memkernel-0.3.0 → memkernel-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memkernel
-Version: 0.3.0
+Version: 0.4.0
 Summary: Code-aware memory server for AI coding copilots
 License: Apache-2.0
 License-File: LICENSE
@@ -27,7 +27,10 @@ Project-URL: Homepage, https://memkernel.dev
 Project-URL: Repository, https://github.com/gosha70/memkernel
 Description-Content-Type: text/markdown
 
-# MemKernel
+<h1>
+  <img src="https://raw.githubusercontent.com/gosha70/memkernel/main/docs/assets/memkernel-logo.png" alt="MemKernel logo: a glowing memory core on three stacked tiers" width="110" align="absmiddle">
+  MemKernel
+</h1>
 
 [![CI](https://github.com/gosha70/memkernel/actions/workflows/ci.yml/badge.svg)](https://github.com/gosha70/memkernel/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/memkernel)](https://pypi.org/project/memkernel/)
@@ -48,23 +51,33 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 
 ## Requirements
 
-- Python 3.11 – 3.13
+- Python 3.11 – 3.13 (the package declares `Requires-Python >=3.11,<3.14`; pip reports "from versions: none" when the installing interpreter is outside that range)
 - [Poetry](https://python-poetry.org) (for development installs)
 
 ---
 
 ## Install
 
+MemKernel is a Python package on PyPI. Its `memkernel` command is the MCP server. There is no npm package: an `npx` install someone suggests is a hallucination.
+
+**Recommended: an isolated install with [pipx](https://pipx.pypa.io)**, which puts the `memkernel` command on your PATH without touching any other Python environment:
+
 ```bash
-pip install memkernel
+pipx install memkernel
+# if pipx's default interpreter is outside 3.11–3.13:
+pipx install --python python3.11 memkernel
 ```
 
-Or with Poetry:
+**As a library inside a project**, install it into that project's virtual environment:
 
 ```bash
-poetry add memkernel
+pip install memkernel        # or: poetry add memkernel
 ```
 
+Avoid a plain `pip install memkernel` into a shared or system interpreter (Homebrew's `python3`, for example). MemKernel pins `chromadb` 1.x and recent `cffi`, so pip will replace older copies and can break unrelated tools that need them.
+
+Verify the install with `pipx list` or `which memkernel`. Running `memkernel` with no arguments starts the MCP server on stdio and waits for a client; `memkernel --version` and `memkernel --help` print and exit.
+
 ---
 
 ## Add to Claude Code
@@ -77,17 +90,29 @@ Add MemKernel to `.claude/settings.json` in your project:
 {
   "mcpServers": {
     "memkernel": {
-      "command": "memkernel",
+      "command": "/Users/you/.local/bin/memkernel",
       "args": [],
       "env": {
-        "MEMKERNEL_PROJECT_ID": "my-project"
+        "MEMKERNEL_PROJECT_ID": "my-project",
+        "MEMKERNEL_CHROMA_PERSIST_PATH": "/Users/you/.memkernel/my-project"
       }
     }
   }
 }
 ```
 
-Replace `my-project` with a short identifier for the project — memories are isolated per project.
+Replace `my-project` with a short identifier for the project — memories are isolated per project. Use the absolute path of the command (`which memkernel` prints it) because Claude Code does not necessarily see the PATH changes your shell profile makes, and an absolute `MEMKERNEL_CHROMA_PERSIST_PATH` keeps the store outside the repository. On first server initialization, MemKernel downloads the embedding model (about 90 MB) if it is not already cached: `build_service()` loads the sentence-transformers model when the MCP server starts, before any tool call, so the first connection can take a minute. Later starts and every tool call are fast.
+
+<details>
+<summary>Troubleshooting the install</summary>
+
+- **`pipx install memkernel` says "No matching distribution found"** — pipx used an interpreter outside 3.11–3.13. Pass one explicitly: `pipx install --python /opt/homebrew/opt/python@3.11/bin/python3.11 memkernel`.
+- **`bash: /some/old/path/memkernel: No such file or directory`** right after reinstalling — the shell cached the old location. Run `hash -r` (bash) or `rehash` (zsh), then `which memkernel`.
+- **`memkernel --help` seems to hang** on versions before 0.4.0 — the command had no flags and started the server; press Ctrl-C. From 0.4.0 on, `--help` and `--version` print and exit.
+- **The first MCP connection is slow or times out** — the server is downloading the embedding model at startup (see above). Wait for it once, or pre-warm it with `python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"` in the same environment.
+- **A global pip install broke another tool** (for example `langchain-chroma` wanting `chromadb < 0.6`) — uninstall memkernel from that interpreter, reinstall the versions the other tool needs, and install memkernel with pipx instead.
+
+</details>
 
 ### 2. Add memory instructions to CLAUDE.md
 
@@ -107,16 +132,30 @@ See the Prerequisites section inside each script for the Python environment requ
 
 ---
 
+## Add to Kiro
+
+Kiro (and the Kiro CLI, formerly Amazon Q Developer CLI) connects to MemKernel as a stdio MCP server. [`templates/kiro/`](templates/kiro/) holds the three files to copy into a workspace:
+
+| Template | Destination | Role |
+|----------|-------------|------|
+| `settings/mcp.json` | `.kiro/settings/mcp.json` | Server entry with `env` and `autoApprove` |
+| `steering/memory.md` | `.kiro/steering/memory.md` | Memory instructions, always included |
+| `hooks/memkernel.json` | `.kiro/hooks/memkernel.json` | `SessionStart` recall, `Stop` retain, manual checkpoint |
+
+[`templates/kiro/README.md`](templates/kiro/README.md) has the setup steps, the Kiro CLI custom-agent variant and the caveats (absolute persist path, hook format by Kiro version).
+
+---
+
 ## MCP Tools
 
 | Tool | What it does |
 |------|-------------|
 | `retain(content, type, session_id?, checkpoint?, source?, importance?, tags?, supersedes?)` | Store a memory. Returns `ref_id`. Idempotent — identical content + type returns the same `ref_id`. `supersedes` hides the memory it replaces. |
-| `recall(query, type?, tier?, session_id?, checkpoint_only?, top_k?)` | Search by natural language or identifier. Returns lightweight `ArtifactRef` list ranked by relevance + recency + importance. Records an access (reinforces retention). |
+| `recall(query, type?, tier?, session_id?, checkpoint_only?, top_k?, include_needs_review?)` | Search by natural language or identifier. Returns lightweight `ArtifactRef` list ranked by relevance + recency + importance. Records an access (reinforces retention). Code memories flagged `needs_review` are hidden unless `include_needs_review=true`. |
 | `get(ref_id)` | Fetch full content of a specific memory. Records an access. |
 | `forget(ref_id)` | Delete a memory from all indexes. |
 | `promote(ref_id, type, content?, importance?, tags?)` | Turn a short-term/working memory into a long-term one (you supply the distilled text). Keeps provenance via `promoted_from`. |
-| `consolidate(session_id?, limit?, synthesize?)` | Purge expired short-term memories and list the ones most worth promoting (ranked by importance × how often they were recalled). `synthesize=true` also asks an external reasoner to draft long-term statements (`suggested`). |
+| `consolidate(session_id?, limit?, synthesize?, revalidate?)` | Purge expired short-term memories and list the ones most worth promoting (ranked by importance × how often they were recalled). `synthesize=true` also asks an external reasoner to draft long-term statements (`suggested`); `revalidate=true` first checks every code memory against its source file (`revalidated`). The report always carries a `health` summary. |
 | `ask(ref_id, question, mode?)` | Answer a question about one memory without loading it — for a `document` the full body is consulted. `mode`: `direct` \| `rag` \| `rlm` \| `auto`, passed to the reasoner unchanged; the built-in reasoner answers in `rag` mode with the best-matching chunks. Returns `answer`, `mode`, `citations`, `usage`. |
 | `wiki_export(wiki_dir?)` | Compile long-term memories without a wiki page into draft markdown pages (`index.md`, `log.md` updated). |
 | `wiki_import(wiki_dir?)` | Index curated wiki pages as long-term memories (idempotent; changed pages supersede). |
@@ -129,7 +168,7 @@ See the Prerequisites section inside each script for the Python environment requ
 | `convention` | long-term | Naming rules, code style, project patterns | 0.9 | Never |
 | `fact` | long-term | Durable project facts: build commands, environments, contracts | 0.7 | Never |
 | `procedure` | long-term | How-to that worked: workflows, recipes, verified skills | 0.8 | Never |
-| `code` | long-term | Function/class snapshots, API contracts | 0.6 | Never |
+| `code` | long-term | Function/class snapshots, API contracts; identified by `(source, content)`, a changed file supersedes the old snapshot, a drifted source flags `needs_review` | 0.6 | Never (superseded on re-retain) |
 | `document` | long-term | Large artefacts (specs, transcripts, files): the body is stored and chunk-indexed, `get` returns a summary, `ask` answers from the indexed chunks (local reasoner) or the body (RLM Studio) | 0.6 | Never |
 | `episode` | short-term | Session events, compaction checkpoints | 0.4 | 30 days, extended by every recall |
 | `observation` | short-term | Findings, tool outputs, things noticed | 0.3 | 7 days, extended by every recall |
@@ -144,6 +183,7 @@ Retention: `ttl = base_ttl × (1 + access_boost × access_count)`, measured from
 3. **Before compaction** — `retain(type="episode", checkpoint=true)` (the `pre-compact.py` hook) and `consolidate()`.
 4. **After compaction / end of phase** — `promote(ref_id, type, content)` for the candidates worth keeping.
 5. **Large artefacts** — `retain(type="document", content=<body>, source=<name>)` then `ask(ref_id, question)`; never `get` a document to read it.
+7. **Code snapshots** — `retain(type="code", content=<file>, source=<path>)`; retain the file again after editing it (the new snapshot supersedes the old one). The session-start hook revalidates snapshots against their files and lists the ones that need re-retaining.
 6. **Curate** — `wiki_export` → review the drafts → `wiki_import`.
 
 ### Quick examples
@@ -199,6 +239,10 @@ All settings are read from environment variables with the `MEMKERNEL_` prefix, o
 | `MEMKERNEL_DOCUMENT_SUMMARY_CHARS` | `1000` | Characters of the body kept in a `document` memory's summary record |
 | `MEMKERNEL_REASONER` | `local` | `ReasonerPort` behind `ask`: `local` (hybrid search over chunks, no LLM) or `rlmstudio` (falls back to `local` when `rlmstudio` is not importable) |
 | `MEMKERNEL_ASK_TOP_K` | `5` | Chunks the local reasoner returns per `ask` |
+| `MEMKERNEL_PROJECT_ROOT` | `.` | Directory that relative `source` paths of `code` memories resolve under; nothing outside it is ever read. Set it whenever the server or a hook is not started from the project directory |
+| `MEMKERNEL_HEALTH_DUPLICATE_THRESHOLD` | `0.95` | Cosine similarity in [0, 1] from which two long-term memories count as near-duplicates in the health pass |
+| `MEMKERNEL_HEALTH_DUPLICATE_LIMIT` | `500` | Most recent long-term memories the near-duplicate check covers |
+| `MEMKERNEL_HEALTH_REPORT_LIMIT` | `20` | Items listed per category in a health report |
 | `MEMKERNEL_EPISODE_TTL_DAYS` | `30` | Base TTL for `episode` memories (short-term) |
 | `MEMKERNEL_OBSERVATION_TTL_DAYS` | `7` | Base TTL for `observation` memories (short-term) |
 | `MEMKERNEL_TASK_TTL_HOURS` | `24` | Base TTL for `task` memories (working) |
@@ -289,6 +333,12 @@ Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](ht
 
 Set `MEMKERNEL_WIKI_DIR` (for example `knowledge/wiki`) or pass `wiki_dir` to the tools. Rationale and the proposed standalone `ai-wiki` repo: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
 
+### Revalidation and store health
+
+A `code` memory is a snapshot of a file. `MemoryService.revalidate()` hashes each live snapshot's whole source file and compares it with the stored content hash: a changed file flags the memory `needs_review` (`changed`), a vanished file flags it `missing`, a matching file clears the flag. Flagged memories leave default `recall` until the file is retained again (which supersedes the stale snapshot) or they are asked for with `include_needs_review=true`. Revalidation runs from `consolidate(revalidate=true)`, at every session start through `MemoryLifecycle.on_session_start()` (a `### Needs review` section lists what to re-retain), and from `POST /revalidate`. Sources resolve under `MEMKERNEL_PROJECT_ROOT` (default: the current directory); set it whenever the server or a hook is not started from the project directory. Nothing outside that root is ever read. 0.4 hashes whole files; per-chunk invalidation is a follow-up.
+
+`MemoryService.health()` audits the store without changing it: orphaned chunk and document records, dangling `supersedes` / `superseded_by` / `promoted_from` / `parent_ref` links, supersessions from 0.2/0.3 that lack the durable marker, `code` memories whose source file is gone, memories flagged for review, expired short-term memories not yet purged and, in full mode only, near-duplicate pairs among the most recent long-term memories (cosine ≥ `MEMKERNEL_HEALTH_DUPLICATE_THRESHOLD`). The quick report (counts only, no embeddings, no content loads) is part of every `consolidate()` report and of the `memory://status` resource; the full report is `GET /health/store`. The pass never fixes anything: a fix mode is a later feature.
+
 ## Admin API
 
 A FastAPI admin server provides health and stats endpoints (independent of MCP):
@@ -302,6 +352,8 @@ uvicorn memkernel.api.app:app --host 127.0.0.1 --port 8766
 | `GET /health` | Server health and memory count |
 | `GET /stats` | Total memory count, per-type and per-tier breakdown, growth rate, last recall latency |
 | `GET /collections` | List ChromaDB collections |
+| `GET /health/store` | Full store health report (orphans, dangling links, stale sources, near-duplicates, …) |
+| `POST /revalidate` | Check every code memory against its source file; flag changed or missing ones |
 
 ---
 
@@ -324,7 +376,7 @@ Releases are published to PyPI by [`.github/workflows/release.yml`](.github/work
 
 1. Set `version` in `pyproject.toml` and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under the new version.
 2. Merge to `main` with CI green.
-3. Tag and push: `git tag -a v0.3.0 -m "memkernel 0.3.0" && git push origin v0.3.0`.
+3. Tag and push: `git tag -a v0.4.0 -m "memkernel 0.4.0" && git push origin v0.4.0`.
 
 The workflow refuses a tag that does not match the `pyproject.toml` version, builds the sdist and wheel, smoke-installs the wheel, and uploads through the `pypi` environment.
 

{memkernel-0.3.0 → memkernel-0.4.0}/README.md

@@ -1,4 +1,7 @@
-# MemKernel
+<h1>
+  <img src="https://raw.githubusercontent.com/gosha70/memkernel/main/docs/assets/memkernel-logo.png" alt="MemKernel logo: a glowing memory core on three stacked tiers" width="110" align="absmiddle">
+  MemKernel
+</h1>
 
 [![CI](https://github.com/gosha70/memkernel/actions/workflows/ci.yml/badge.svg)](https://github.com/gosha70/memkernel/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/memkernel)](https://pypi.org/project/memkernel/)
@@ -19,23 +22,33 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 
 ## Requirements
 
-- Python 3.11 – 3.13
+- Python 3.11 – 3.13 (the package declares `Requires-Python >=3.11,<3.14`; pip reports "from versions: none" when the installing interpreter is outside that range)
 - [Poetry](https://python-poetry.org) (for development installs)
 
 ---
 
 ## Install
 
+MemKernel is a Python package on PyPI. Its `memkernel` command is the MCP server. There is no npm package: an `npx` install someone suggests is a hallucination.
+
+**Recommended: an isolated install with [pipx](https://pipx.pypa.io)**, which puts the `memkernel` command on your PATH without touching any other Python environment:
+
 ```bash
-pip install memkernel
+pipx install memkernel
+# if pipx's default interpreter is outside 3.11–3.13:
+pipx install --python python3.11 memkernel
 ```
 
-Or with Poetry:
+**As a library inside a project**, install it into that project's virtual environment:
 
 ```bash
-poetry add memkernel
+pip install memkernel        # or: poetry add memkernel
 ```
 
+Avoid a plain `pip install memkernel` into a shared or system interpreter (Homebrew's `python3`, for example). MemKernel pins `chromadb` 1.x and recent `cffi`, so pip will replace older copies and can break unrelated tools that need them.
+
+Verify the install with `pipx list` or `which memkernel`. Running `memkernel` with no arguments starts the MCP server on stdio and waits for a client; `memkernel --version` and `memkernel --help` print and exit.
+
 ---
 
 ## Add to Claude Code
@@ -48,17 +61,29 @@ Add MemKernel to `.claude/settings.json` in your project:
 {
   "mcpServers": {
     "memkernel": {
-      "command": "memkernel",
+      "command": "/Users/you/.local/bin/memkernel",
       "args": [],
       "env": {
-        "MEMKERNEL_PROJECT_ID": "my-project"
+        "MEMKERNEL_PROJECT_ID": "my-project",
+        "MEMKERNEL_CHROMA_PERSIST_PATH": "/Users/you/.memkernel/my-project"
       }
     }
   }
 }
 ```
 
-Replace `my-project` with a short identifier for the project — memories are isolated per project.
+Replace `my-project` with a short identifier for the project — memories are isolated per project. Use the absolute path of the command (`which memkernel` prints it) because Claude Code does not necessarily see the PATH changes your shell profile makes, and an absolute `MEMKERNEL_CHROMA_PERSIST_PATH` keeps the store outside the repository. On first server initialization, MemKernel downloads the embedding model (about 90 MB) if it is not already cached: `build_service()` loads the sentence-transformers model when the MCP server starts, before any tool call, so the first connection can take a minute. Later starts and every tool call are fast.
+
+<details>
+<summary>Troubleshooting the install</summary>
+
+- **`pipx install memkernel` says "No matching distribution found"** — pipx used an interpreter outside 3.11–3.13. Pass one explicitly: `pipx install --python /opt/homebrew/opt/python@3.11/bin/python3.11 memkernel`.
+- **`bash: /some/old/path/memkernel: No such file or directory`** right after reinstalling — the shell cached the old location. Run `hash -r` (bash) or `rehash` (zsh), then `which memkernel`.
+- **`memkernel --help` seems to hang** on versions before 0.4.0 — the command had no flags and started the server; press Ctrl-C. From 0.4.0 on, `--help` and `--version` print and exit.
+- **The first MCP connection is slow or times out** — the server is downloading the embedding model at startup (see above). Wait for it once, or pre-warm it with `python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"` in the same environment.
+- **A global pip install broke another tool** (for example `langchain-chroma` wanting `chromadb < 0.6`) — uninstall memkernel from that interpreter, reinstall the versions the other tool needs, and install memkernel with pipx instead.
+
+</details>
 
 ### 2. Add memory instructions to CLAUDE.md
 
@@ -78,16 +103,30 @@ See the Prerequisites section inside each script for the Python environment requ
 
 ---
 
+## Add to Kiro
+
+Kiro (and the Kiro CLI, formerly Amazon Q Developer CLI) connects to MemKernel as a stdio MCP server. [`templates/kiro/`](templates/kiro/) holds the three files to copy into a workspace:
+
+| Template | Destination | Role |
+|----------|-------------|------|
+| `settings/mcp.json` | `.kiro/settings/mcp.json` | Server entry with `env` and `autoApprove` |
+| `steering/memory.md` | `.kiro/steering/memory.md` | Memory instructions, always included |
+| `hooks/memkernel.json` | `.kiro/hooks/memkernel.json` | `SessionStart` recall, `Stop` retain, manual checkpoint |
+
+[`templates/kiro/README.md`](templates/kiro/README.md) has the setup steps, the Kiro CLI custom-agent variant and the caveats (absolute persist path, hook format by Kiro version).
+
+---
+
 ## MCP Tools
 
 | Tool | What it does |
 |------|-------------|
 | `retain(content, type, session_id?, checkpoint?, source?, importance?, tags?, supersedes?)` | Store a memory. Returns `ref_id`. Idempotent — identical content + type returns the same `ref_id`. `supersedes` hides the memory it replaces. |
-| `recall(query, type?, tier?, session_id?, checkpoint_only?, top_k?)` | Search by natural language or identifier. Returns lightweight `ArtifactRef` list ranked by relevance + recency + importance. Records an access (reinforces retention). |
+| `recall(query, type?, tier?, session_id?, checkpoint_only?, top_k?, include_needs_review?)` | Search by natural language or identifier. Returns lightweight `ArtifactRef` list ranked by relevance + recency + importance. Records an access (reinforces retention). Code memories flagged `needs_review` are hidden unless `include_needs_review=true`. |
 | `get(ref_id)` | Fetch full content of a specific memory. Records an access. |
 | `forget(ref_id)` | Delete a memory from all indexes. |
 | `promote(ref_id, type, content?, importance?, tags?)` | Turn a short-term/working memory into a long-term one (you supply the distilled text). Keeps provenance via `promoted_from`. |
-| `consolidate(session_id?, limit?, synthesize?)` | Purge expired short-term memories and list the ones most worth promoting (ranked by importance × how often they were recalled). `synthesize=true` also asks an external reasoner to draft long-term statements (`suggested`). |
+| `consolidate(session_id?, limit?, synthesize?, revalidate?)` | Purge expired short-term memories and list the ones most worth promoting (ranked by importance × how often they were recalled). `synthesize=true` also asks an external reasoner to draft long-term statements (`suggested`); `revalidate=true` first checks every code memory against its source file (`revalidated`). The report always carries a `health` summary. |
 | `ask(ref_id, question, mode?)` | Answer a question about one memory without loading it — for a `document` the full body is consulted. `mode`: `direct` \| `rag` \| `rlm` \| `auto`, passed to the reasoner unchanged; the built-in reasoner answers in `rag` mode with the best-matching chunks. Returns `answer`, `mode`, `citations`, `usage`. |
 | `wiki_export(wiki_dir?)` | Compile long-term memories without a wiki page into draft markdown pages (`index.md`, `log.md` updated). |
 | `wiki_import(wiki_dir?)` | Index curated wiki pages as long-term memories (idempotent; changed pages supersede). |
@@ -100,7 +139,7 @@ See the Prerequisites section inside each script for the Python environment requ
 | `convention` | long-term | Naming rules, code style, project patterns | 0.9 | Never |
 | `fact` | long-term | Durable project facts: build commands, environments, contracts | 0.7 | Never |
 | `procedure` | long-term | How-to that worked: workflows, recipes, verified skills | 0.8 | Never |
-| `code` | long-term | Function/class snapshots, API contracts | 0.6 | Never |
+| `code` | long-term | Function/class snapshots, API contracts; identified by `(source, content)`, a changed file supersedes the old snapshot, a drifted source flags `needs_review` | 0.6 | Never (superseded on re-retain) |
 | `document` | long-term | Large artefacts (specs, transcripts, files): the body is stored and chunk-indexed, `get` returns a summary, `ask` answers from the indexed chunks (local reasoner) or the body (RLM Studio) | 0.6 | Never |
 | `episode` | short-term | Session events, compaction checkpoints | 0.4 | 30 days, extended by every recall |
 | `observation` | short-term | Findings, tool outputs, things noticed | 0.3 | 7 days, extended by every recall |
@@ -115,6 +154,7 @@ Retention: `ttl = base_ttl × (1 + access_boost × access_count)`, measured from
 3. **Before compaction** — `retain(type="episode", checkpoint=true)` (the `pre-compact.py` hook) and `consolidate()`.
 4. **After compaction / end of phase** — `promote(ref_id, type, content)` for the candidates worth keeping.
 5. **Large artefacts** — `retain(type="document", content=<body>, source=<name>)` then `ask(ref_id, question)`; never `get` a document to read it.
+7. **Code snapshots** — `retain(type="code", content=<file>, source=<path>)`; retain the file again after editing it (the new snapshot supersedes the old one). The session-start hook revalidates snapshots against their files and lists the ones that need re-retaining.
 6. **Curate** — `wiki_export` → review the drafts → `wiki_import`.
 
 ### Quick examples
@@ -170,6 +210,10 @@ All settings are read from environment variables with the `MEMKERNEL_` prefix, o
 | `MEMKERNEL_DOCUMENT_SUMMARY_CHARS` | `1000` | Characters of the body kept in a `document` memory's summary record |
 | `MEMKERNEL_REASONER` | `local` | `ReasonerPort` behind `ask`: `local` (hybrid search over chunks, no LLM) or `rlmstudio` (falls back to `local` when `rlmstudio` is not importable) |
 | `MEMKERNEL_ASK_TOP_K` | `5` | Chunks the local reasoner returns per `ask` |
+| `MEMKERNEL_PROJECT_ROOT` | `.` | Directory that relative `source` paths of `code` memories resolve under; nothing outside it is ever read. Set it whenever the server or a hook is not started from the project directory |
+| `MEMKERNEL_HEALTH_DUPLICATE_THRESHOLD` | `0.95` | Cosine similarity in [0, 1] from which two long-term memories count as near-duplicates in the health pass |
+| `MEMKERNEL_HEALTH_DUPLICATE_LIMIT` | `500` | Most recent long-term memories the near-duplicate check covers |
+| `MEMKERNEL_HEALTH_REPORT_LIMIT` | `20` | Items listed per category in a health report |
 | `MEMKERNEL_EPISODE_TTL_DAYS` | `30` | Base TTL for `episode` memories (short-term) |
 | `MEMKERNEL_OBSERVATION_TTL_DAYS` | `7` | Base TTL for `observation` memories (short-term) |
 | `MEMKERNEL_TASK_TTL_HOURS` | `24` | Base TTL for `task` memories (working) |
@@ -260,6 +304,12 @@ Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](ht
 
 Set `MEMKERNEL_WIKI_DIR` (for example `knowledge/wiki`) or pass `wiki_dir` to the tools. Rationale and the proposed standalone `ai-wiki` repo: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
 
+### Revalidation and store health
+
+A `code` memory is a snapshot of a file. `MemoryService.revalidate()` hashes each live snapshot's whole source file and compares it with the stored content hash: a changed file flags the memory `needs_review` (`changed`), a vanished file flags it `missing`, a matching file clears the flag. Flagged memories leave default `recall` until the file is retained again (which supersedes the stale snapshot) or they are asked for with `include_needs_review=true`. Revalidation runs from `consolidate(revalidate=true)`, at every session start through `MemoryLifecycle.on_session_start()` (a `### Needs review` section lists what to re-retain), and from `POST /revalidate`. Sources resolve under `MEMKERNEL_PROJECT_ROOT` (default: the current directory); set it whenever the server or a hook is not started from the project directory. Nothing outside that root is ever read. 0.4 hashes whole files; per-chunk invalidation is a follow-up.
+
+`MemoryService.health()` audits the store without changing it: orphaned chunk and document records, dangling `supersedes` / `superseded_by` / `promoted_from` / `parent_ref` links, supersessions from 0.2/0.3 that lack the durable marker, `code` memories whose source file is gone, memories flagged for review, expired short-term memories not yet purged and, in full mode only, near-duplicate pairs among the most recent long-term memories (cosine ≥ `MEMKERNEL_HEALTH_DUPLICATE_THRESHOLD`). The quick report (counts only, no embeddings, no content loads) is part of every `consolidate()` report and of the `memory://status` resource; the full report is `GET /health/store`. The pass never fixes anything: a fix mode is a later feature.
+
 ## Admin API
 
 A FastAPI admin server provides health and stats endpoints (independent of MCP):
@@ -273,6 +323,8 @@ uvicorn memkernel.api.app:app --host 127.0.0.1 --port 8766
 | `GET /health` | Server health and memory count |
 | `GET /stats` | Total memory count, per-type and per-tier breakdown, growth rate, last recall latency |
 | `GET /collections` | List ChromaDB collections |
+| `GET /health/store` | Full store health report (orphans, dangling links, stale sources, near-duplicates, …) |
+| `POST /revalidate` | Check every code memory against its source file; flag changed or missing ones |
 
 ---
 
@@ -295,7 +347,7 @@ Releases are published to PyPI by [`.github/workflows/release.yml`](.github/work
 
 1. Set `version` in `pyproject.toml` and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under the new version.
 2. Merge to `main` with CI green.
-3. Tag and push: `git tag -a v0.3.0 -m "memkernel 0.3.0" && git push origin v0.3.0`.
+3. Tag and push: `git tag -a v0.4.0 -m "memkernel 0.4.0" && git push origin v0.4.0`.
 
 The workflow refuses a tag that does not match the `pyproject.toml` version, builds the sdist and wheel, smoke-installs the wheel, and uploads through the `pypi` environment.
 

{memkernel-0.3.0 → memkernel-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "memkernel"
-version = "0.3.0"
+version = "0.4.0"
 description = "Code-aware memory server for AI coding copilots"
 authors = ["EGOGE"]
 license = "Apache-2.0"

{memkernel-0.3.0 → memkernel-0.4.0}/src/memkernel/__init__.py

@@ -2,4 +2,4 @@
 # SPDX-License-Identifier: Apache-2.0
 """MemKernel — Code-aware memory server for AI coding copilots."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{memkernel-0.3.0 → memkernel-0.4.0}/src/memkernel/api/routes/admin.py

@@ -1,6 +1,6 @@
 # Copyright (c) 2026 EGOGE
 # SPDX-License-Identifier: Apache-2.0
-"""Admin API route handlers: /health, /stats, /collections."""
+"""Admin API route handlers: /health, /health/store, /stats, /collections, /revalidate."""
 
 from __future__ import annotations
 
@@ -30,6 +30,14 @@ async def health(request: Request) -> dict[str, Any]:
     }
 
 
+@router.get("/health/store")
+async def health_store(request: Request) -> dict[str, Any]:
+    """Read-only store health report: orphans, dangling links, stale sources, near-duplicates and more."""
+    svc = _svc(request)
+    report = svc.health()
+    return {**report.model_dump(mode="json"), "summary": report.summary}
+
+
 @router.get("/stats")
 async def stats(request: Request) -> dict[str, Any]:
     """Memory metrics: per-type breakdown, growth by time window, last recall latency."""
@@ -42,3 +50,10 @@ async def collections(request: Request) -> list[dict[str, Any]]:
     """List all project collections with record counts."""
     svc = _svc(request)
     return svc.list_collections()
+
+
+@router.post("/revalidate")
+async def revalidate(request: Request) -> dict[str, Any]:
+    """Check every code memory against its source file; flag changed or missing ones (needs_review)."""
+    svc = _svc(request)
+    return svc.revalidate()

{memkernel-0.3.0 → memkernel-0.4.0}/src/memkernel/config.py

@@ -40,6 +40,14 @@ class MemKernelSettings(BaseSettings):
     reasoner: Literal["local", "rlmstudio"] = "local"  # ReasonerPort behind ask(); falls back to local
     ask_top_k: int = 5  # chunks the local reasoner returns per ask()
 
+    # Sources, revalidation and store health (0.4)
+    project_root: str = "."  # relative `source` paths resolve under this directory; nothing outside it is read
+    health_duplicate_threshold: float = (
+        0.95  # cosine similarity in [0, 1] from which two long-term memories are near-duplicates
+    )
+    health_duplicate_limit: int = 500  # most recent long-term memories checked for near-duplicates
+    health_report_limit: int = 20  # items listed per health category
+
     # Lifecycle / decay (see docs/architecture/memory-tiers.md)
     episode_ttl_days: int = 30  # base TTL for short-term `episode` memories
     observation_ttl_days: int = 7  # base TTL for short-term `observation` memories

{memkernel-0.3.0 → memkernel-0.4.0}/src/memkernel/core/models.py

@@ -95,12 +95,48 @@ DOCUMENT_PART_KEY = "document_part"
 ASK_MODES: tuple[str, ...] = ("direct", "rag", "rlm", "auto")
 DEFAULT_ASK_MODE = "auto"
 
+# Chunk records of a `code` memory (0.4): owner-specific index entries, never
+# deduplicated by content, tagged and linked to their canonical record.
+CODE_CHUNK_TAG = "code_chunk"
+CODE_CHUNK_KEY = "code_chunk"  # boolean metadata so adapters can skip chunk records
+PARENT_REF_KEY = "parent_ref"
+# Durable liveness marker (0.4): set on a record that another record replaced.
+SUPERSEDED_BY_KEY = "superseded_by"
+# Revalidation flags (0.4).
+NEEDS_REVIEW_KEY = "needs_review"
+REVIEW_REASON_KEY = "review_reason"
+REVIEW_REASON_CHANGED = "changed"
+REVIEW_REASON_MISSING = "missing"
+
 
 def tier_of(memory_type: MemoryType) -> MemoryTier:
     """Return the tier a memory type belongs to."""
     return TYPE_TIER[memory_type]
 
 
+# Type values of the long-term tier: the health pass filters neighbours on
+# these, never on the `tier` key, which records written before 0.2 lack.
+LONG_TERM_TYPE_VALUES: tuple[str, ...] = tuple(t.value for t, tier in TYPE_TIER.items() if tier == MemoryTier.LONG_TERM)
+
+# Health report categories (0.4), in report order.
+HEALTH_ORPHANS = "orphans"
+HEALTH_DANGLING_LINKS = "dangling_links"
+HEALTH_UNMARKED_SUPERSESSIONS = "unmarked_supersessions"
+HEALTH_STALE_SOURCES = "stale_sources"
+HEALTH_NEEDS_REVIEW = "needs_review"
+HEALTH_EXPIRED_PRESENT = "expired_present"
+HEALTH_NEAR_DUPLICATES = "near_duplicates"
+HEALTH_CATEGORIES: tuple[str, ...] = (
+    HEALTH_ORPHANS,
+    HEALTH_DANGLING_LINKS,
+    HEALTH_UNMARKED_SUPERSESSIONS,
+    HEALTH_STALE_SOURCES,
+    HEALTH_NEEDS_REVIEW,
+    HEALTH_EXPIRED_PRESENT,
+    HEALTH_NEAR_DUPLICATES,
+)
+
+
 class Memory(BaseModel):
     """A stored unit of knowledge with full content and metadata."""
 
@@ -127,6 +163,43 @@ class Memory(BaseModel):
     # Set on a ``document`` summary record and on the body/chunk records the
     # document store keeps for it (ADR-009).
     document_id: str | None = None
+    # 0.4: durable marker on a replaced record; owner link on a code chunk
+    # record; revalidation flags. All load with defaults from older stores.
+    superseded_by: str | None = None
+    parent_ref: str | None = None
+    needs_review: bool = False
+    review_reason: str = ""
+
+
+class HealthItem(BaseModel):
+    """One finding of the store health pass.
+
+    For ``near_duplicates`` an item is one pair: ``ref_id`` is the
+    lexicographically smaller id and ``detail`` is ``"~ <other id> (cosine x)"``;
+    neither side is "the original".
+    """
+
+    ref_id: str
+    detail: str
+
+
+class HealthReport(BaseModel):
+    """Read-only store health report: per category, every finding counted and up to a bounded number listed."""
+
+    full: bool = True
+    counts: dict[str, int] = {}
+    orphans: list[HealthItem] = []
+    dangling_links: list[HealthItem] = []
+    unmarked_supersessions: list[HealthItem] = []
+    stale_sources: list[HealthItem] = []
+    needs_review: list[HealthItem] = []
+    expired_present: list[HealthItem] = []
+    near_duplicates: list[HealthItem] = []
+
+    @property
+    def summary(self) -> dict[str, int]:
+        """``{category: count}`` — the counts-only view used by the status resource and consolidate reports."""
+        return dict(self.counts)
 
 
 class ReasonerError(RuntimeError):

{memkernel-0.3.0 → memkernel-0.4.0}/src/memkernel/core/ports.py

@@ -37,10 +37,16 @@ class VectorStorePort(Protocol):
 
     def delete(self, ref_id: str) -> bool: ...
 
-    def list_all(self, where: dict[str, Any] | None = None) -> list[Memory]: ...
+    def list_all(self, where: dict[str, Any] | None = None, include_content: bool = True) -> list[Memory]:
+        """All records matching ``where``; ``include_content=False`` fetches ids and metadata only (content empty)."""
+        ...
+
+    def find_by_hash(self, content_hash: str, memory_type: str, source: str | None = None) -> Memory | None:
+        """Find by content_hash + type, optionally + source (dedup key per ADR-5 / 0.4 sourced-code identity).
 
-    def find_by_hash(self, content_hash: str, memory_type: str) -> Memory | None:
-        """Find by content_hash + type (dedup key per ADR-5)."""
+        Never returns a code chunk record (a single-chunk file cannot shadow its
+        canonical) nor a superseded record (history is not a dedup hit).
+        """
         ...
 
     def update_metadata(self, ref_id: str, metadata: dict[str, Any]) -> None: