memkernel 0.5.0__tar.gz → 0.6.0__tar.gz

{memkernel-0.5.0 → memkernel-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memkernel
-Version: 0.5.0
+Version: 0.6.0
 Summary: Code-aware memory server for AI coding copilots
 License: Apache-2.0
 License-File: LICENSE
@@ -23,7 +23,7 @@ Requires-Dist: rank-bm25 (>=0.2)
 Requires-Dist: sentence-transformers (>=4.0,<6)
 Requires-Dist: tree-sitter (>=0.22,<1)
 Requires-Dist: tree-sitter-python (>=0.23)
-Requires-Dist: wiki-studio (>=0.3.1,<1) ; extra == "wiki"
+Requires-Dist: wiki-studio (>=0.7.0,<1) ; extra == "wiki"
 Project-URL: Documentation, https://memkernel.dev
 Project-URL: Homepage, https://memkernel.dev
 Project-URL: Repository, https://github.com/gosha70/memkernel
@@ -65,7 +65,7 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 - **An index of the whole repository.** `code` memories are the snapshots the agent chose to retain, not an automatic scan of every file.
 - **A cross-project knowledge base.** One store per project id. Sharing is deliberate: a second server with a shared id, or the wiki bridge.
 
-**Evidence.** `eval/run_eval.py` measures retrieval (recall@k, precision@k, MRR). The 0.5 lifecycle evaluation, a **maintainer-run supplemental evaluation** (memkernel's own runner, preregistered and announced in [#17](https://github.com/gosha70/memkernel/issues/17) before the run), ran the same agent in seven arms on 20 tasks: [report](eval/lifecycle-suite/report-0.5.0.md). **No gain is claimed.** Against files alone (`claude_md`), memkernel's memory store was ahead on 6 tasks, behind on none and tied on 14 (Holm-adjusted p 0.0625: "no detectable difference"; with so many ties this task set could not have reached significance); against earlier transcripts (`fs_grep`) it was equivalent. Two of the four task groups hit a ceiling, every arm passing every trial. The report's disclosures list its deviations and known defects. Results are published per minor release, including the cases with no gain.
+**Evidence.** `eval/run_eval.py` measures retrieval (recall@k, precision@k, MRR). The 0.5 lifecycle evaluation, a **maintainer-run supplemental evaluation** (memkernel's own runner, preregistered and announced in [#17](https://github.com/gosha70/memkernel/issues/17) before the run), ran the same agent in seven arms on 20 tasks: [report](eval/lifecycle-suite/report-0.5.0.md). **No gain is claimed.** Against files alone (`claude_md`), memkernel's memory store was ahead on 6 tasks, behind on none and tied on 14 (Holm-adjusted p 0.0625: "no detectable difference"; with so many ties this task set could not have reached significance); against earlier transcripts (`fs_grep`) it was equivalent. Two of the four task groups hit a ceiling, every arm passing every trial. The report's disclosures list its deviations and known defects. Results are published with the cases that show no gain; the 0.5 report is the latest evaluation, and 0.6.0 had no new measured run.
 
 ---
 
@@ -88,7 +88,7 @@ pipx install memkernel
 pipx install --python python3.11 memkernel
 # optional: wiki-studio lint and health findings on wiki_export (ADR-010)
 pipx install "memkernel[wiki]"
-pipx inject memkernel "wiki-studio>=0.3.1,<1"   # add it to an existing install
+pipx inject memkernel "wiki-studio>=0.7.0,<1"   # add it to an existing install
 ```
 
 **As a library inside a project**, install it into that project's virtual environment:
@@ -147,9 +147,11 @@ Copy the hook scripts from [`templates/hooks/`](templates/hooks/) to `.claude/ho
 
 | Hook | Claude Code event | What it does |
 |------|-------------------|--------------|
-| `session-start.py` | `SessionStart` | Consolidates, recovers the latest checkpoint and long-term context, lists promotion candidates |
-| `pre-compact.py` | `PreCompact` | Retains a checkpoint episode, runs a consolidation pass |
-| `post-compact.py` | `PostCompact` | Re-injects the checkpoint, long-term context and promotion candidates |
+| `session-start.py` | `SessionStart` | By `source`: on `startup` and `clear`, consolidates, recovers the latest checkpoint and long-term context, lists promotion candidates; on `compact`, the recovery after a compaction (the latest checkpoint the agent saved, with its age, and long-term context; no consolidation); on `resume` and `fork`, nothing |
+| `pre-compact.py` | `PreCompact` | Runs a consolidation pass (Claude Code passes no summary here, so no checkpoint is retained) |
+| `post-compact.py` | `PostCompact` | Retains Claude Code's compaction summary (`compact_summary`) as a checkpoint for the next session; prints nothing for the model |
+
+Register `SessionStart` without a matcher, so it runs for every `source`. Claude Code adds only `SessionStart`'s output to the model's context, not `PreCompact`'s or `PostCompact`'s, so the recovery after a compaction comes from `SessionStart` with `source: "compact"`. After upgrading memkernel, copy the three scripts again.
 
 See the Prerequisites section inside each script for the Python environment requirement. Each script is a thin wrapper over [`MemoryLifecycle`](#embedding-memkernel-in-your-own-harness), so an in-process harness gets the same behaviour without the scripts.
 
@@ -181,7 +183,7 @@ Kiro (and the Kiro CLI, formerly Amazon Q Developer CLI) connects to MemKernel a
 | `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). |
+| `wiki_import(wiki_dir?)` | Index wiki pages as long-term memories: approved revisions only with wiki-studio ≥ 0.7.0, every page without it (idempotent; changed pages supersede; `corrects` supersedes the memories a page corrects). |
 
 ### Memory types and tiers
 
@@ -201,13 +203,13 @@ Retention: `ttl = base_ttl × (1 + access_boost × access_count)`, measured from
 
 ### Session protocol
 
-1. **Session start** — `recall(tier="long_term", query=<task>)`, plus the latest checkpoint (`checkpoint_only=true`). The `session-start.py` hook does this and prints promotion candidates.
+1. **Session start** — `recall(tier="long_term", query=<task>)`, plus the latest checkpoint (`checkpoint_only=true`). The `session-start.py` hook does this and prints promotion candidates; after a compaction it prints a shorter recovery block instead.
 2. **While working** — `retain(type="task")` when the plan changes; `retain(type="observation")` for findings; durable knowledge as `decision` / `convention` / `fact` / `procedure`.
-3. **Before compaction** — `retain(type="episode", checkpoint=true)` (the `pre-compact.py` hook) and `consolidate()`.
+3. **Before compaction** — `retain(type="episode", checkpoint=true)` with your own summary of where the work stands; the `pre-compact.py` hook runs `consolidate()`, and the `post-compact.py` hook keeps Claude Code's compaction summary as a checkpoint.
 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`.
+6. **Curate** — `wiki_export` → review and approve the drafts in wiki-studio → `wiki_import`.
 
 ### Quick examples
 
@@ -251,7 +253,7 @@ setting is logged as a warning at startup.
 |----------|---------|-------------|
 | `MEMKERNEL_PROJECT_ID` | `default` | Project namespace — memories are isolated per project |
 | `MEMKERNEL_DEFAULT_SESSION_ID` | `default` | Session tag applied when `session_id` is omitted from `retain` |
-| `MEMKERNEL_CHROMA_PERSIST_PATH` | `.memkernel/chroma` | ChromaDB data directory. Empty string = in-memory (ephemeral) |
+| `MEMKERNEL_CHROMA_PERSIST_PATH` | `.memkernel/chroma` | ChromaDB data directory. Empty string = in-memory (ephemeral). On POSIX systems (Linux, macOS), opening it takes a short lock on `.memkernel-open.lock` inside it, so the MCP server and a hook opening a new store at once do not collide; where `fcntl` is unavailable (Windows) the store opens without the lock, and two processes creating a new store at the same moment can still fail |
 | `MEMKERNEL_CHROMA_COLLECTION_PREFIX` | `memkernel` | Prefix for ChromaDB collection names (`{prefix}_{project_id}`) |
 | `MEMKERNEL_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name |
 | `MEMKERNEL_EMBEDDING_DIMENSION` | `384` | Output dimension of the embedding model |
@@ -323,7 +325,7 @@ report = svc.consolidate()                 # {"purged": n, "candidates": [...]}
 
 ### The session protocol as a component
 
-`MemoryLifecycle` packages what the hook scripts do, so a harness calls four methods instead of re-implementing the protocol. Every method returns markdown ready for injection and does nothing but talk to the service:
+`MemoryLifecycle` packages what the hook scripts do, so a harness calls five methods instead of re-implementing the protocol. Every method returns markdown ready for injection and does nothing but talk to the service:
 
 ```python
 from memkernel.factory import build_service
@@ -332,9 +334,13 @@ from memkernel.lifecycle import MemoryLifecycle
 memory = MemoryLifecycle(build_service())
 system_context = memory.on_session_start()       # checkpoint, long-term context, promotion candidates, wiki pointer
 ...
-memory.on_pre_compact(summary)                   # checkpoint episode + consolidation, before the context is compacted
-recovered = memory.on_post_compact()             # what to re-inject after compaction
+memory.on_pre_compact(summary)                   # checkpoint episode (only if summary is not blank) + consolidation
+recovered = memory.on_post_compact()             # what to re-inject after your own compaction
 memory.on_session_end(summary)                   # final checkpoint + consolidation
+
+# Driving it from Claude Code's hook events instead (what templates/hooks/ do):
+memory.on_session_start(source)                  # source "startup"/"clear": full block; "compact": recovery block; "resume"/"fork": ""
+memory.capture_compact_summary(compact_summary, session_id=..., trigger=...)  # keep Claude Code's own summary as a checkpoint
 ```
 
 ### Documents and `ask`
@@ -355,11 +361,12 @@ memory.on_session_end(summary)                   # final checkpoint + consolidat
 Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern (`index.md`, `log.md`, typed pages with cited sources — the same schema as `code-copilot-team/knowledge/wiki`).
 
 - `wiki_export` compiles every long-term memory that has no page yet into a **draft** page under `decisions/`, `concepts/` or `workflows/`, with the required sections and a `memkernel://<project>/<ref_id>` citation. Existing pages are never overwritten.
-- `wiki_import` indexes curated pages as long-term memories so `recall` finds the reviewed version; a changed page supersedes its earlier memory.
+- `wiki_import` indexes pages as long-term memories so `recall` finds the reviewed version; a changed page supersedes its earlier memory. With wiki-studio 0.7.0 or later installed it is **governed** (`"governed": true`): it imports only pages wiki-studio's review state reports approved, and only when the page's bytes are still the approved revision, so drafts, self-declared approvals and pages edited after approval are not imported (`not_approved` says why); an edited page keeps its last approved memory until it is approved again. memkernel never approves a page; a curator does, with `wiki-studio approve`. Without wiki-studio the import reads the page files, drafts included, and reports `"governed": false`. An installed wiki-studio that is broken or older than 0.7.0 imports nothing and reports `import_error`.
+- **Corrections.** An approved page can name the memories it corrects in its frontmatter: `corrects: <ref_id>, <ref_id>` (one line; tokens of letters, digits, `-` and `_`). On import each named memory that did not come from the wiki is superseded by the page's memory: it stops being a current answer, and its record is kept. References that cannot be applied are listed in `unresolved` with a reason (unknown, another project's, already superseded, or a wiki memory: correct that page instead); a value that breaks the grammar is listed in `invalid_corrects`, and the page is still imported. An approved page that is already current is listed in `unchanged`, and its corrections are reconciled again on every import, so a reference that could not be applied earlier takes effect once it can; corrections already applied are not repeated.
 
 Set `MEMKERNEL_WIKI_DIR` (for example `knowledge/wiki`) or pass `wiki_dir` to the tools. The standalone maintainer that owns this page schema is [wiki-studio](https://github.com/gosha70/wiki-studio). With the `memkernel[wiki]` extra installed, every `wiki_export` response carries wiki-studio's lint and health findings for the whole wiki after the export, curated pages included, under `lint` (`violations`, `audit_errors`, `pages_checked`, `health` items with `kind`, `severity`, `pages`, `description`); without it `lint` is `null` and `lint_hint` says how to enable it; if the lint pass itself fails, `lint` is `null` and `lint_error` says why. The files written are the same in every case.
 
-With wiki-studio 0.3.1 or later installed, `wiki_export` writes through wiki-studio's promote gate: it first writes `index.md` and `log.md` if they are missing (the gate cannot create them), then proposes every new page with its index and log lines as one patch-set and promotes it. A rejected export writes nothing and the response carries `gate_error`; so does an installed wiki-studio that fails to import or to build the patch-set, rather than falling back to the direct writer. A failed export leaves its patch-set under the proposals directory for inspection; delete it once the cause is fixed. Patch-sets go to `MEMKERNEL_WIKI_PROPOSALS_DIR`, by default `.memkernel/wiki-proposals/` under the project root. Commit `<wiki>/.audit/`, wiki-studio's audit trail of promoted proposals; ignore `.memkernel/wiki-proposals/`.
+With wiki-studio 0.7.0 or later installed, `wiki_export` writes through wiki-studio's promote gate: wiki-studio's `init` creates `index.md` and `log.md` if they are missing (wiki-studio's own scaffold, `status: stable`), then every new page goes with its index and log lines into one patch-set that is proposed and promoted. Other writers can work in the same wiki: wiki-studio's commit writes only the paths the patch-set names, under its lock, and refuses a page someone else created in the meantime. A rejected export writes no page and the response carries `gate_error` (a new wiki keeps the `index.md` and `log.md` that `init` created); so does an installed wiki-studio that is broken or older than 0.7.0, rather than falling back to the direct writer. A promoted export's response adds `proposal`, `submission_digest` and `archived_dir` from wiki-studio's receipt. If `archived_dir` is `null`, the pages landed but wiki-studio did not finish: it could not archive the proposal, or it failed after committing the pages (memkernel checks wiki-studio's receipt: while it still says `committing`, every planned write, index and log included, must be at its post-write sha256; a `committed` receipt needs memkernel's pages at theirs; an unusable receipt falls back to comparing the pages' bytes). `archive_hint` gives the `promote` command that tries to finish it, with absolute paths, so it runs from any directory. It applies nothing twice, but if the wiki or the proposal changed since, for example another writer appended to `index.md`, it may refuse with `uncertain_outcome` or `payload_changed` and write nothing; then compare the wiki with the proposal's `receipt.json` by hand. memkernel never runs it itself. If wiki-studio failed during its commit and its receipt shows neither a commit nor a rollback (say the page was written, the `index.md` write failed and removing the page failed too), the response carries `gate_error` with `uncertain_outcome` and `proposal`: `written` is empty, but the pages it names may be on disk; compare the wiki with the `receipt.json` it names before exporting again. `receipt_error` says the receipt could not be read or used. A failed export leaves its patch-set under the proposals directory for inspection; delete it once the cause is fixed. Patch-sets go to `MEMKERNEL_WIKI_PROPOSALS_DIR`, by default `.memkernel/wiki-proposals/` under the project root. Commit `<wiki>/.audit/`, wiki-studio's audit trail of promoted proposals; ignore `.memkernel/wiki-proposals/` and wiki-studio's lock file next to the wiki directory, `.<wiki-dir>.wiki-studio.lock` (for `knowledge/wiki`, `knowledge/.wiki.wiki-studio.lock`).
 
 Rationale: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md) and [`docs/adr/ADR-010-wiki-studio-as-wiki-maintainer.md`](docs/adr/ADR-010-wiki-studio-as-wiki-maintainer.md).
 
@@ -404,9 +411,15 @@ CI runs on every push and PR: lint, type check, tests (≥ 80% coverage), securi
 
 Releases are published to PyPI by [`.github/workflows/release.yml`](.github/workflows/release.yml) using trusted publishing (no token in the repo). To cut a release:
 
-1. Set `version` in `pyproject.toml` and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under the new version.
+1. Set `version` in `pyproject.toml` and `__version__` in `src/memkernel/__init__.py` to `X.Y.Z`, and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under `[X.Y.Z] - <tag date>`.
 2. Merge to `main` with CI green.
-3. Tag and push: `git tag -a v0.4.0 -m "memkernel 0.4.0" && git push origin v0.4.0`.
+3. Tag and push: `git tag -a vX.Y.Z -m "memkernel X.Y.Z" && git push origin vX.Y.Z`.
+4. Create the GitHub Release from the tag, with the version's CHANGELOG section as its notes:
+
+   ```bash
+   awk -v v=X.Y.Z 'index($0, "## [" v "]") == 1 {f=1; next} f && /^## \[/ {exit} f' CHANGELOG.md > release-notes.md
+   gh release create vX.Y.Z --title X.Y.Z --notes-file release-notes.md --verify-tag
+   ```
 
 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.5.0 → memkernel-0.6.0}/README.md

@@ -34,7 +34,7 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 - **An index of the whole repository.** `code` memories are the snapshots the agent chose to retain, not an automatic scan of every file.
 - **A cross-project knowledge base.** One store per project id. Sharing is deliberate: a second server with a shared id, or the wiki bridge.
 
-**Evidence.** `eval/run_eval.py` measures retrieval (recall@k, precision@k, MRR). The 0.5 lifecycle evaluation, a **maintainer-run supplemental evaluation** (memkernel's own runner, preregistered and announced in [#17](https://github.com/gosha70/memkernel/issues/17) before the run), ran the same agent in seven arms on 20 tasks: [report](eval/lifecycle-suite/report-0.5.0.md). **No gain is claimed.** Against files alone (`claude_md`), memkernel's memory store was ahead on 6 tasks, behind on none and tied on 14 (Holm-adjusted p 0.0625: "no detectable difference"; with so many ties this task set could not have reached significance); against earlier transcripts (`fs_grep`) it was equivalent. Two of the four task groups hit a ceiling, every arm passing every trial. The report's disclosures list its deviations and known defects. Results are published per minor release, including the cases with no gain.
+**Evidence.** `eval/run_eval.py` measures retrieval (recall@k, precision@k, MRR). The 0.5 lifecycle evaluation, a **maintainer-run supplemental evaluation** (memkernel's own runner, preregistered and announced in [#17](https://github.com/gosha70/memkernel/issues/17) before the run), ran the same agent in seven arms on 20 tasks: [report](eval/lifecycle-suite/report-0.5.0.md). **No gain is claimed.** Against files alone (`claude_md`), memkernel's memory store was ahead on 6 tasks, behind on none and tied on 14 (Holm-adjusted p 0.0625: "no detectable difference"; with so many ties this task set could not have reached significance); against earlier transcripts (`fs_grep`) it was equivalent. Two of the four task groups hit a ceiling, every arm passing every trial. The report's disclosures list its deviations and known defects. Results are published with the cases that show no gain; the 0.5 report is the latest evaluation, and 0.6.0 had no new measured run.
 
 ---
 
@@ -57,7 +57,7 @@ pipx install memkernel
 pipx install --python python3.11 memkernel
 # optional: wiki-studio lint and health findings on wiki_export (ADR-010)
 pipx install "memkernel[wiki]"
-pipx inject memkernel "wiki-studio>=0.3.1,<1"   # add it to an existing install
+pipx inject memkernel "wiki-studio>=0.7.0,<1"   # add it to an existing install
 ```
 
 **As a library inside a project**, install it into that project's virtual environment:
@@ -116,9 +116,11 @@ Copy the hook scripts from [`templates/hooks/`](templates/hooks/) to `.claude/ho
 
 | Hook | Claude Code event | What it does |
 |------|-------------------|--------------|
-| `session-start.py` | `SessionStart` | Consolidates, recovers the latest checkpoint and long-term context, lists promotion candidates |
-| `pre-compact.py` | `PreCompact` | Retains a checkpoint episode, runs a consolidation pass |
-| `post-compact.py` | `PostCompact` | Re-injects the checkpoint, long-term context and promotion candidates |
+| `session-start.py` | `SessionStart` | By `source`: on `startup` and `clear`, consolidates, recovers the latest checkpoint and long-term context, lists promotion candidates; on `compact`, the recovery after a compaction (the latest checkpoint the agent saved, with its age, and long-term context; no consolidation); on `resume` and `fork`, nothing |
+| `pre-compact.py` | `PreCompact` | Runs a consolidation pass (Claude Code passes no summary here, so no checkpoint is retained) |
+| `post-compact.py` | `PostCompact` | Retains Claude Code's compaction summary (`compact_summary`) as a checkpoint for the next session; prints nothing for the model |
+
+Register `SessionStart` without a matcher, so it runs for every `source`. Claude Code adds only `SessionStart`'s output to the model's context, not `PreCompact`'s or `PostCompact`'s, so the recovery after a compaction comes from `SessionStart` with `source: "compact"`. After upgrading memkernel, copy the three scripts again.
 
 See the Prerequisites section inside each script for the Python environment requirement. Each script is a thin wrapper over [`MemoryLifecycle`](#embedding-memkernel-in-your-own-harness), so an in-process harness gets the same behaviour without the scripts.
 
@@ -150,7 +152,7 @@ Kiro (and the Kiro CLI, formerly Amazon Q Developer CLI) connects to MemKernel a
 | `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). |
+| `wiki_import(wiki_dir?)` | Index wiki pages as long-term memories: approved revisions only with wiki-studio ≥ 0.7.0, every page without it (idempotent; changed pages supersede; `corrects` supersedes the memories a page corrects). |
 
 ### Memory types and tiers
 
@@ -170,13 +172,13 @@ Retention: `ttl = base_ttl × (1 + access_boost × access_count)`, measured from
 
 ### Session protocol
 
-1. **Session start** — `recall(tier="long_term", query=<task>)`, plus the latest checkpoint (`checkpoint_only=true`). The `session-start.py` hook does this and prints promotion candidates.
+1. **Session start** — `recall(tier="long_term", query=<task>)`, plus the latest checkpoint (`checkpoint_only=true`). The `session-start.py` hook does this and prints promotion candidates; after a compaction it prints a shorter recovery block instead.
 2. **While working** — `retain(type="task")` when the plan changes; `retain(type="observation")` for findings; durable knowledge as `decision` / `convention` / `fact` / `procedure`.
-3. **Before compaction** — `retain(type="episode", checkpoint=true)` (the `pre-compact.py` hook) and `consolidate()`.
+3. **Before compaction** — `retain(type="episode", checkpoint=true)` with your own summary of where the work stands; the `pre-compact.py` hook runs `consolidate()`, and the `post-compact.py` hook keeps Claude Code's compaction summary as a checkpoint.
 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`.
+6. **Curate** — `wiki_export` → review and approve the drafts in wiki-studio → `wiki_import`.
 
 ### Quick examples
 
@@ -220,7 +222,7 @@ setting is logged as a warning at startup.
 |----------|---------|-------------|
 | `MEMKERNEL_PROJECT_ID` | `default` | Project namespace — memories are isolated per project |
 | `MEMKERNEL_DEFAULT_SESSION_ID` | `default` | Session tag applied when `session_id` is omitted from `retain` |
-| `MEMKERNEL_CHROMA_PERSIST_PATH` | `.memkernel/chroma` | ChromaDB data directory. Empty string = in-memory (ephemeral) |
+| `MEMKERNEL_CHROMA_PERSIST_PATH` | `.memkernel/chroma` | ChromaDB data directory. Empty string = in-memory (ephemeral). On POSIX systems (Linux, macOS), opening it takes a short lock on `.memkernel-open.lock` inside it, so the MCP server and a hook opening a new store at once do not collide; where `fcntl` is unavailable (Windows) the store opens without the lock, and two processes creating a new store at the same moment can still fail |
 | `MEMKERNEL_CHROMA_COLLECTION_PREFIX` | `memkernel` | Prefix for ChromaDB collection names (`{prefix}_{project_id}`) |
 | `MEMKERNEL_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name |
 | `MEMKERNEL_EMBEDDING_DIMENSION` | `384` | Output dimension of the embedding model |
@@ -292,7 +294,7 @@ report = svc.consolidate()                 # {"purged": n, "candidates": [...]}
 
 ### The session protocol as a component
 
-`MemoryLifecycle` packages what the hook scripts do, so a harness calls four methods instead of re-implementing the protocol. Every method returns markdown ready for injection and does nothing but talk to the service:
+`MemoryLifecycle` packages what the hook scripts do, so a harness calls five methods instead of re-implementing the protocol. Every method returns markdown ready for injection and does nothing but talk to the service:
 
 ```python
 from memkernel.factory import build_service
@@ -301,9 +303,13 @@ from memkernel.lifecycle import MemoryLifecycle
 memory = MemoryLifecycle(build_service())
 system_context = memory.on_session_start()       # checkpoint, long-term context, promotion candidates, wiki pointer
 ...
-memory.on_pre_compact(summary)                   # checkpoint episode + consolidation, before the context is compacted
-recovered = memory.on_post_compact()             # what to re-inject after compaction
+memory.on_pre_compact(summary)                   # checkpoint episode (only if summary is not blank) + consolidation
+recovered = memory.on_post_compact()             # what to re-inject after your own compaction
 memory.on_session_end(summary)                   # final checkpoint + consolidation
+
+# Driving it from Claude Code's hook events instead (what templates/hooks/ do):
+memory.on_session_start(source)                  # source "startup"/"clear": full block; "compact": recovery block; "resume"/"fork": ""
+memory.capture_compact_summary(compact_summary, session_id=..., trigger=...)  # keep Claude Code's own summary as a checkpoint
 ```
 
 ### Documents and `ask`
@@ -324,11 +330,12 @@ memory.on_session_end(summary)                   # final checkpoint + consolidat
 Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern (`index.md`, `log.md`, typed pages with cited sources — the same schema as `code-copilot-team/knowledge/wiki`).
 
 - `wiki_export` compiles every long-term memory that has no page yet into a **draft** page under `decisions/`, `concepts/` or `workflows/`, with the required sections and a `memkernel://<project>/<ref_id>` citation. Existing pages are never overwritten.
-- `wiki_import` indexes curated pages as long-term memories so `recall` finds the reviewed version; a changed page supersedes its earlier memory.
+- `wiki_import` indexes pages as long-term memories so `recall` finds the reviewed version; a changed page supersedes its earlier memory. With wiki-studio 0.7.0 or later installed it is **governed** (`"governed": true`): it imports only pages wiki-studio's review state reports approved, and only when the page's bytes are still the approved revision, so drafts, self-declared approvals and pages edited after approval are not imported (`not_approved` says why); an edited page keeps its last approved memory until it is approved again. memkernel never approves a page; a curator does, with `wiki-studio approve`. Without wiki-studio the import reads the page files, drafts included, and reports `"governed": false`. An installed wiki-studio that is broken or older than 0.7.0 imports nothing and reports `import_error`.
+- **Corrections.** An approved page can name the memories it corrects in its frontmatter: `corrects: <ref_id>, <ref_id>` (one line; tokens of letters, digits, `-` and `_`). On import each named memory that did not come from the wiki is superseded by the page's memory: it stops being a current answer, and its record is kept. References that cannot be applied are listed in `unresolved` with a reason (unknown, another project's, already superseded, or a wiki memory: correct that page instead); a value that breaks the grammar is listed in `invalid_corrects`, and the page is still imported. An approved page that is already current is listed in `unchanged`, and its corrections are reconciled again on every import, so a reference that could not be applied earlier takes effect once it can; corrections already applied are not repeated.
 
 Set `MEMKERNEL_WIKI_DIR` (for example `knowledge/wiki`) or pass `wiki_dir` to the tools. The standalone maintainer that owns this page schema is [wiki-studio](https://github.com/gosha70/wiki-studio). With the `memkernel[wiki]` extra installed, every `wiki_export` response carries wiki-studio's lint and health findings for the whole wiki after the export, curated pages included, under `lint` (`violations`, `audit_errors`, `pages_checked`, `health` items with `kind`, `severity`, `pages`, `description`); without it `lint` is `null` and `lint_hint` says how to enable it; if the lint pass itself fails, `lint` is `null` and `lint_error` says why. The files written are the same in every case.
 
-With wiki-studio 0.3.1 or later installed, `wiki_export` writes through wiki-studio's promote gate: it first writes `index.md` and `log.md` if they are missing (the gate cannot create them), then proposes every new page with its index and log lines as one patch-set and promotes it. A rejected export writes nothing and the response carries `gate_error`; so does an installed wiki-studio that fails to import or to build the patch-set, rather than falling back to the direct writer. A failed export leaves its patch-set under the proposals directory for inspection; delete it once the cause is fixed. Patch-sets go to `MEMKERNEL_WIKI_PROPOSALS_DIR`, by default `.memkernel/wiki-proposals/` under the project root. Commit `<wiki>/.audit/`, wiki-studio's audit trail of promoted proposals; ignore `.memkernel/wiki-proposals/`.
+With wiki-studio 0.7.0 or later installed, `wiki_export` writes through wiki-studio's promote gate: wiki-studio's `init` creates `index.md` and `log.md` if they are missing (wiki-studio's own scaffold, `status: stable`), then every new page goes with its index and log lines into one patch-set that is proposed and promoted. Other writers can work in the same wiki: wiki-studio's commit writes only the paths the patch-set names, under its lock, and refuses a page someone else created in the meantime. A rejected export writes no page and the response carries `gate_error` (a new wiki keeps the `index.md` and `log.md` that `init` created); so does an installed wiki-studio that is broken or older than 0.7.0, rather than falling back to the direct writer. A promoted export's response adds `proposal`, `submission_digest` and `archived_dir` from wiki-studio's receipt. If `archived_dir` is `null`, the pages landed but wiki-studio did not finish: it could not archive the proposal, or it failed after committing the pages (memkernel checks wiki-studio's receipt: while it still says `committing`, every planned write, index and log included, must be at its post-write sha256; a `committed` receipt needs memkernel's pages at theirs; an unusable receipt falls back to comparing the pages' bytes). `archive_hint` gives the `promote` command that tries to finish it, with absolute paths, so it runs from any directory. It applies nothing twice, but if the wiki or the proposal changed since, for example another writer appended to `index.md`, it may refuse with `uncertain_outcome` or `payload_changed` and write nothing; then compare the wiki with the proposal's `receipt.json` by hand. memkernel never runs it itself. If wiki-studio failed during its commit and its receipt shows neither a commit nor a rollback (say the page was written, the `index.md` write failed and removing the page failed too), the response carries `gate_error` with `uncertain_outcome` and `proposal`: `written` is empty, but the pages it names may be on disk; compare the wiki with the `receipt.json` it names before exporting again. `receipt_error` says the receipt could not be read or used. A failed export leaves its patch-set under the proposals directory for inspection; delete it once the cause is fixed. Patch-sets go to `MEMKERNEL_WIKI_PROPOSALS_DIR`, by default `.memkernel/wiki-proposals/` under the project root. Commit `<wiki>/.audit/`, wiki-studio's audit trail of promoted proposals; ignore `.memkernel/wiki-proposals/` and wiki-studio's lock file next to the wiki directory, `.<wiki-dir>.wiki-studio.lock` (for `knowledge/wiki`, `knowledge/.wiki.wiki-studio.lock`).
 
 Rationale: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md) and [`docs/adr/ADR-010-wiki-studio-as-wiki-maintainer.md`](docs/adr/ADR-010-wiki-studio-as-wiki-maintainer.md).
 
@@ -373,9 +380,15 @@ CI runs on every push and PR: lint, type check, tests (≥ 80% coverage), securi
 
 Releases are published to PyPI by [`.github/workflows/release.yml`](.github/workflows/release.yml) using trusted publishing (no token in the repo). To cut a release:
 
-1. Set `version` in `pyproject.toml` and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under the new version.
+1. Set `version` in `pyproject.toml` and `__version__` in `src/memkernel/__init__.py` to `X.Y.Z`, and move the `[Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under `[X.Y.Z] - <tag date>`.
 2. Merge to `main` with CI green.
-3. Tag and push: `git tag -a v0.4.0 -m "memkernel 0.4.0" && git push origin v0.4.0`.
+3. Tag and push: `git tag -a vX.Y.Z -m "memkernel X.Y.Z" && git push origin vX.Y.Z`.
+4. Create the GitHub Release from the tag, with the version's CHANGELOG section as its notes:
+
+   ```bash
+   awk -v v=X.Y.Z 'index($0, "## [" v "]") == 1 {f=1; next} f && /^## \[/ {exit} f' CHANGELOG.md > release-notes.md
+   gh release create vX.Y.Z --title X.Y.Z --notes-file release-notes.md --verify-tag
+   ```
 
 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.5.0 → memkernel-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "memkernel"
-version = "0.5.0"
+version = "0.6.0"
 description = "Code-aware memory server for AI coding copilots"
 authors = ["EGOGE"]
 license = "Apache-2.0"
@@ -32,7 +32,7 @@ pydantic = ">=2.0,<3"
 pydantic-settings = ">=2.0,<3"
 fastapi = ">=0.115,<1"
 # Optional integrations (ADR-010): installed only through an extra; imported lazily.
-wiki-studio = { version = ">=0.3.1,<1", optional = true }
+wiki-studio = { version = ">=0.7.0,<1", optional = true }
 
 [tool.poetry.extras]
 wiki = ["wiki-studio"]
@@ -45,7 +45,7 @@ ruff = ">=0.9"
 mypy = ">=1.13"
 httpx = ">=0.27"
 pip-audit = "^2.10.0"
-wiki-studio = ">=0.3.1,<1"
+wiki-studio = ">=0.7.0,<1"
 
 [build-system]
 requires = ["poetry-core"]

{memkernel-0.5.0 → memkernel-0.6.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.5.0"
+__version__ = "0.6.0"

{memkernel-0.5.0 → memkernel-0.6.0}/src/memkernel/core/services.py

@@ -259,6 +259,8 @@ class MemoryService:
         tags: list[str] | None = None,
         supersedes: str | None = None,
         promoted_from: str | None = None,
+        *,
+        dedup_source: bool = False,
     ) -> str:
         """Store content and return its ref_id.
 
@@ -277,7 +279,10 @@ class MemoryService:
         memkernel record keeps only a summary (``get`` never returns the
         body; use ``ask``). ``source`` names the document.
 
-        Idempotent: identical content + type returns the existing ref_id.
+        Idempotent: identical content + type returns the existing ref_id. With
+        ``dedup_source`` a single record's dedup hit also requires the same ``source``
+        (memkernel-0-6 FR-012: one memory per wiki page, never merged with another
+        page's or an agent's identical text).
         """
         extra = _ExtraMeta(importance=importance, tags=tags or [], supersedes=supersedes, promoted_from=promoted_from)
         if type == MemoryType.DOCUMENT and self._document_store is not None:
@@ -285,7 +290,7 @@ class MemoryService:
         if type == MemoryType.CODE:
             return self._retain_code(content, session_id, checkpoint, source, extra)
 
-        return self._retain_single(content, type, session_id, checkpoint, source, extra)
+        return self._retain_single(content, type, session_id, checkpoint, source, extra, dedup_source=dedup_source)
 
     def _retain_code(
         self,
@@ -450,13 +455,47 @@ class MemoryService:
             ):
                 self._vector_store.update_metadata(chunk.ref_id, update)
 
+    def supersede(self, ref_id: str, by_ref: str) -> bool:
+        """Mark the existing record ``ref_id`` as replaced by the existing record ``by_ref``.
+
+        Sets only the durable ``superseded_by`` marker (on ``ref_id`` and its owned
+        chunks), as ``retain(supersedes=...)`` does; the record's content and every
+        other field stay as they are, so its provenance remains. Returns True when it
+        set the marker, False when ``ref_id`` was already superseded by ``by_ref``; that
+        call still marks any owned chunk left without the marker, so a retry completes
+        a partial mark.
+        Raises ``ValueError`` and changes nothing when either record is not in this
+        store (unknown, or another project's), when they are the same record, or when
+        ``ref_id`` is already superseded by a different record: an existing marker is
+        never overwritten.
+        """
+        if ref_id == by_ref:
+            raise ValueError(f"{ref_id} cannot supersede itself")
+        target = self._vector_store.get_by_id(ref_id)
+        if target is None:
+            raise ValueError(f"{ref_id} is not a memory in this store")
+        if self._vector_store.get_by_id(by_ref) is None:
+            raise ValueError(f"{by_ref} is not a memory in this store")
+        if target.superseded_by == by_ref:
+            self._mark_superseded(ref_id, by_ref)  # idempotent: repairs chunks a failed earlier mark left
+            return False
+        if target.superseded_by:
+            raise ValueError(f"{ref_id} is already superseded by {target.superseded_by}")
+        self._mark_superseded(ref_id, by_ref)
+        return True
+
     def _mark_superseded(self, target_ref: str, by_ref: str) -> None:
-        """Set the durable ``superseded_by`` marker on ``target_ref`` and its owned chunks."""
+        """Set the durable ``superseded_by`` marker on ``target_ref``'s owned chunks, then on ``target_ref``.
+
+        The record is marked last: it is what ``supersede`` checks, so a failure part-way leaves it unmarked and
+        a retry marks everything. Only chunks without a marker are written: an existing marker is never overwritten.
+        """
         if target_ref == by_ref or self._vector_store.get_by_id(target_ref) is None:
             return
-        self._vector_store.update_metadata(target_ref, {SUPERSEDED_BY_KEY: by_ref})
         for chunk in self._owned_chunks(target_ref):
-            self._vector_store.update_metadata(chunk.ref_id, {SUPERSEDED_BY_KEY: by_ref})
+            if not chunk.superseded_by:
+                self._vector_store.update_metadata(chunk.ref_id, {SUPERSEDED_BY_KEY: by_ref})
+        self._vector_store.update_metadata(target_ref, {SUPERSEDED_BY_KEY: by_ref})
 
     def _delete_owned_chunks(self, canonical: Memory) -> None:
         """Delete a canonical's owned chunk records; legacy shared chunk_refs only when nothing else references them."""
@@ -523,18 +562,21 @@ class MemoryService:
         source: str,
         extra: _ExtraMeta | None = None,
         dedup: bool = True,
+        dedup_source: bool = False,
     ) -> str:
         """Store a single content string and return its ref_id.
 
         ``dedup=False`` skips the content-hash check for records whose identity
-        is not their text (document summaries).
+        is not their text (document summaries); ``dedup_source`` scopes it to
+        records with the same ``source``.
         """
         extra = extra or _ExtraMeta()
         resolved_session = session_id or self._settings.default_session_id
         content_hash = compute_content_hash(content)
 
         # Dedup check: same hash + same type -> update metadata, return existing id
-        existing = self._vector_store.find_by_hash(content_hash, type.value) if dedup else None
+        scope = source if dedup_source else None
+        existing = self._vector_store.find_by_hash(content_hash, type.value, source=scope) if dedup else None
         if existing is not None:
             self._refresh_existing(existing, resolved_session, checkpoint, extra)
             return existing.ref_id
@@ -782,6 +824,25 @@ class MemoryService:
             memories = [m for m in memories if m.tier == tier]
         return memories
 
+    def checkpoints_newest_first(self) -> list[Memory]:
+        """Every live checkpoint record, newest first (ties by ``ref_id``), without content and without touching.
+
+        Selected by metadata, so the newest is found however many older checkpoints a query would rank higher.
+        Live as for :meth:`recall`, judged with this service's settings: not superseded, not flagged for review,
+        not expired. Code-chunk and document-part records are left out: they are parts of a checkpoint, not one.
+        Read the chosen record with :meth:`get`.
+        """
+        live = [
+            m
+            for m in self._vector_store.list_all({"checkpoint": True}, include_content=False)
+            if m.superseded_by is None
+            and not m.needs_review
+            and m.parent_ref is None
+            and not _is_document_part(m)
+            and not memory_is_expired(m, self._settings)
+        ]
+        return sorted(live, key=lambda m: (m.timestamp, m.ref_id), reverse=True)
+
     @property
     def project_id(self) -> str:
         """Return the project_id for this service instance."""