memkernel 0.4.1__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memkernel
-Version: 0.4.1
+Version: 0.5.0
 Summary: Code-aware memory server for AI coding copilots
 License: Apache-2.0
 License-File: LICENSE
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
+Provides-Extra: wiki
 Requires-Dist: chromadb (>=1.0,<2)
 Requires-Dist: fastapi (>=0.115,<1)
 Requires-Dist: mcp (>=1.25,<2)
@@ -22,6 +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"
 Project-URL: Documentation, https://memkernel.dev
 Project-URL: Homepage, https://memkernel.dev
 Project-URL: Repository, https://github.com/gosha70/memkernel
@@ -63,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). An agent-level benchmark that runs the same agent with and without MemKernel, including a negative control where files already carry all state, is tracked in [#17](https://github.com/gosha70/memkernel/issues/17). Results will be 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 per minor release, including the cases with no gain.
 
 ---
 
@@ -84,6 +86,9 @@ MemKernel is a Python package on PyPI. Its `memkernel` command is the MCP server
 pipx install memkernel
 # if pipx's default interpreter is outside 3.11–3.13:
 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
 ```
 
 **As a library inside a project**, install it into that project's virtual environment:
@@ -272,6 +277,7 @@ setting is logged as a warning at startup.
 | `MEMKERNEL_RECALL_WEIGHT_RECENCY` | `0.3` | Weight of recency in the final recall score |
 | `MEMKERNEL_RECALL_WEIGHT_IMPORTANCE` | `0.3` | Weight of importance in the final recall score |
 | `MEMKERNEL_WIKI_DIR` | `` | Directory of the LLM wiki used by `wiki_export` / `wiki_import` (empty = pass `wiki_dir` explicitly) |
+| `MEMKERNEL_WIKI_PROPOSALS_DIR` | `""` | Where wiki-studio patch-sets are written before promote (`memkernel[wiki]`); empty means `<project root>/.memkernel/wiki-proposals`. Setting it requests the gate: without wiki-studio installed, a warning is logged. |
 | `MEMKERNEL_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
 | `MEMKERNEL_HOST` | `127.0.0.1` | Host for `streamable-http` transport |
 | `MEMKERNEL_PORT` | `8765` | Port for `streamable-http` transport |
@@ -351,7 +357,11 @@ Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](ht
 - `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.
 
-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) (`pip install wiki-studio`; `wiki-studio lint --health` checks what `wiki_export` writes). Rationale: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
+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/`.
+
+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).
 
 ### Revalidation and store health
 

{memkernel-0.4.1 → memkernel-0.5.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). An agent-level benchmark that runs the same agent with and without MemKernel, including a negative control where files already carry all state, is tracked in [#17](https://github.com/gosha70/memkernel/issues/17). Results will be 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 per minor release, including the cases with no gain.
 
 ---
 
@@ -55,6 +55,9 @@ MemKernel is a Python package on PyPI. Its `memkernel` command is the MCP server
 pipx install memkernel
 # if pipx's default interpreter is outside 3.11–3.13:
 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
 ```
 
 **As a library inside a project**, install it into that project's virtual environment:
@@ -243,6 +246,7 @@ setting is logged as a warning at startup.
 | `MEMKERNEL_RECALL_WEIGHT_RECENCY` | `0.3` | Weight of recency in the final recall score |
 | `MEMKERNEL_RECALL_WEIGHT_IMPORTANCE` | `0.3` | Weight of importance in the final recall score |
 | `MEMKERNEL_WIKI_DIR` | `` | Directory of the LLM wiki used by `wiki_export` / `wiki_import` (empty = pass `wiki_dir` explicitly) |
+| `MEMKERNEL_WIKI_PROPOSALS_DIR` | `""` | Where wiki-studio patch-sets are written before promote (`memkernel[wiki]`); empty means `<project root>/.memkernel/wiki-proposals`. Setting it requests the gate: without wiki-studio installed, a warning is logged. |
 | `MEMKERNEL_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
 | `MEMKERNEL_HOST` | `127.0.0.1` | Host for `streamable-http` transport |
 | `MEMKERNEL_PORT` | `8765` | Port for `streamable-http` transport |
@@ -322,7 +326,11 @@ Long-term memory has a human-readable twin: a markdown wiki in the [LLM Wiki](ht
 - `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.
 
-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) (`pip install wiki-studio`; `wiki-studio lint --health` checks what `wiki_export` writes). Rationale: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
+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/`.
+
+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).
 
 ### Revalidation and store health
 

{memkernel-0.4.1 → memkernel-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "memkernel"
-version = "0.4.1"
+version = "0.5.0"
 description = "Code-aware memory server for AI coding copilots"
 authors = ["EGOGE"]
 license = "Apache-2.0"
@@ -31,6 +31,11 @@ tree-sitter-python = ">=0.23"
 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 }
+
+[tool.poetry.extras]
+wiki = ["wiki-studio"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = ">=8"
@@ -40,7 +45,7 @@ ruff = ">=0.9"
 mypy = ">=1.13"
 httpx = ">=0.27"
 pip-audit = "^2.10.0"
-wiki-studio = ">=0.1,<1"
+wiki-studio = ">=0.3.1,<1"
 
 [build-system]
 requires = ["poetry-core"]

{memkernel-0.4.1 → memkernel-0.5.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.4.1"
+__version__ = "0.5.0"

{memkernel-0.4.1 → memkernel-0.5.0}/src/memkernel/config.py

@@ -76,6 +76,9 @@ class MemKernelSettings(BaseSettings):
     # LLM wiki bridge: directory holding the markdown wiki (index.md, decisions/, ...).
     # Empty = no wiki configured; wiki_export/wiki_import then require an explicit path.
     wiki_dir: str = ""
+    # Where wiki-studio patch-sets are written before promote (memkernel[wiki], ADR-010).
+    # Empty = <project_root>/.memkernel/wiki-proposals; set it to request the gate explicitly.
+    wiki_proposals_dir: str = ""
 
     # Server
     transport: Literal["stdio", "streamable-http"] = "stdio"

{memkernel-0.4.1 → memkernel-0.5.0}/src/memkernel/mcp/tools/wiki.py

@@ -11,6 +11,7 @@ from typing import Any
 from mcp.server.fastmcp import FastMCP  # noqa: TC002 — runtime import required by FastMCP introspection
 from mcp.server.fastmcp.server import Context  # noqa: TC002
 
+from memkernel.wiki.studio import INSTALL_HINT
 from memkernel.wiki.sync import WikiExporter, WikiImporter
 
 
@@ -38,11 +39,35 @@ def register_wiki_tools(server: FastMCP[Any]) -> None:
         """Compile long-term memories (decision, convention, fact, procedure) that have no wiki
         page yet into draft markdown pages under wiki_dir (default MEMKERNEL_WIKI_DIR), and
         append them to index.md and log.md. Review and curate the drafts before marking stable.
+        With the memkernel[wiki] extra installed, "lint" carries wiki-studio's violations, audit
+        errors and health findings for the whole wiki after the export (curated pages included);
+        without the extra it is null and "lint_hint" says how to enable it; if the lint pass itself
+        failed it is null and "lint_error" says why. With wiki-studio >= 0.3 the pages go through its
+        promote gate (index.md and log.md are scaffolded first); a rejected export, or an installed but
+        broken wiki-studio, writes nothing and reports "gate_error". The pages, index.md and log.md
+        written are the same either way.
         """
         app_ctx = _context(ctx)
-        exporter = WikiExporter(app_ctx.memory_service, _resolve_wiki_dir(wiki_dir, app_ctx.settings))
+        proposals = app_ctx.settings.wiki_proposals_dir
+        exporter = WikiExporter(
+            app_ctx.memory_service,
+            _resolve_wiki_dir(wiki_dir, app_ctx.settings),
+            project_root=Path(app_ctx.settings.project_root),
+            proposals_dir=Path(proposals) if proposals else None,
+        )
         report = exporter.export()
-        return json.dumps({"written": report.written, "skipped": report.skipped})
+        payload: dict[str, Any] = {"written": report.written, "skipped": report.skipped}
+        if report.gate_error is not None:
+            payload["gate_error"] = report.gate_error
+        if report.lint is not None:
+            payload["lint"] = report.lint.model_dump(mode="json")
+        elif report.lint_error is not None:
+            payload["lint"] = None
+            payload["lint_error"] = report.lint_error
+        else:
+            payload["lint"] = None
+            payload["lint_hint"] = INSTALL_HINT
+        return json.dumps(payload)
 
     @server.tool()
     async def wiki_import(

memkernel-0.5.0/src/memkernel/wiki/studio.py

@@ -0,0 +1,193 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""Optional wiki-studio integration (the ``memkernel[wiki]`` extra, ADR-010).
+
+wiki-studio owns the wiki page schema and its lint and health pass. This
+module is the only place memkernel imports it, lazily: without the extra
+every function here returns ``None`` and logs nothing, because a missing
+optional extra is a normal state. A warning is logged only when the caller
+asked for wiki-studio explicitly (``require_studio=True``). Nothing here ever calls
+wiki-studio's ``ingest``, ``query`` or a copilot-CLI backend: those shell out
+to a copilot CLI, and memkernel runs inside one.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+INSTALL_HINT = "install memkernel[wiki] for lint and health"
+GATE_BACKEND = "memkernel"
+GATE_RATIONALE = "memkernel export"
+
+
+class HealthItem(BaseModel):
+    """One knowledge-health finding, field for field as wiki-studio's ``HealthFinding``."""
+
+    kind: str
+    severity: str
+    pages: list[str]
+    description: str
+
+
+class LintSummary(BaseModel):
+    """wiki-studio's structural lint, audit-format and health results for one wiki directory."""
+
+    violations: list[str] = Field(default_factory=list)
+    audit_errors: list[str] = Field(default_factory=list)
+    pages_checked: int = 0
+    health: list[HealthItem] | None = None
+
+
+class LintError(RuntimeError):
+    """wiki-studio is installed but its lint pass failed; the export itself is unaffected."""
+
+
+def load_studio(*, require_studio: bool = False) -> Any | None:
+    """Return the ``wiki_studio.api`` module, or ``None`` when the extra is not installed.
+
+    Only a missing ``wiki_studio`` package counts as absence. Any other import
+    failure means the package is present but broken or incompatible, which is
+    raised as :class:`LintError` so it is reported rather than mistaken for the
+    extra being absent.
+    """
+    try:
+        import wiki_studio.api as api
+    except ModuleNotFoundError as exc:
+        if exc.name == "wiki_studio":
+            if require_studio:
+                logger.warning("wiki-studio is not installed; %s", INSTALL_HINT)
+            return None
+        raise LintError(f"wiki-studio is installed but broken: {exc}") from exc
+    except Exception as exc:  # ImportError or any error raised while the package initialises
+        raise LintError(f"wiki-studio is installed but broken: {exc}") from exc
+    return api
+
+
+def lint_wiki(wiki_dir: Path, project_root: Path, *, require_studio: bool = False) -> LintSummary | None:
+    """Run wiki-studio's lint with the health checks over the whole wiki in ``wiki_dir``.
+
+    Returns ``None`` without the extra. Raises :class:`LintError` for every failure
+    of an installed wiki-studio: a broken or incompatible package, a page that is
+    not valid UTF-8, a malformed audit tree, a result whose shape memkernel does
+    not recognise. The caller decides what the failure means for its own result.
+    ``project_root`` is the root ``path:`` sources resolve against (memkernel's
+    ``MEMKERNEL_PROJECT_ROOT``). No backend is passed, so the LLM-dependent
+    contradiction check is skipped.
+    """
+    try:
+        api = load_studio(require_studio=require_studio)
+        if api is None:
+            return None
+        from wiki_studio.paths import WikiPaths
+
+        result = api.lint(WikiPaths.for_root(project_root, wiki_dir=wiki_dir), health=True)
+        health = (
+            [
+                HealthItem(
+                    kind=str(finding.kind),
+                    severity=str(finding.severity),
+                    pages=list(finding.pages),
+                    description=finding.description,
+                )
+                for finding in result.health.findings
+            ]
+            if result.health is not None
+            else None
+        )
+        return LintSummary(
+            violations=list(result.violations),
+            audit_errors=list(result.audit_errors),
+            pages_checked=result.pages_checked,
+            health=health,
+        )
+    except LintError as exc:  # broken installation, already wrapped by load_studio
+        logger.warning("wiki-studio lint failed for %s: %s", wiki_dir, exc)
+        raise
+    except Exception as exc:  # third-party failure of an installed package: wrapped, never silent
+        logger.warning("wiki-studio lint failed for %s: %s", wiki_dir, exc)
+        raise LintError(f"wiki-studio lint failed: {exc}") from exc
+
+
+class GateError(RuntimeError):
+    """wiki-studio's gate rejected or failed to apply an export; the pages were not written."""
+
+
+@dataclass(frozen=True)
+class GatedPage:
+    """One page of an export as the gate needs it: the page itself plus its index and log lines."""
+
+    path: str  # wiki-relative, e.g. "decisions/use-arq.md"
+    content: str
+    index_line: str | None  # one line of the export's single append-index edit; None = no entry
+    log_line: str | None  # one line of the export's single append-log edit; None = no entry
+
+
+def gate_available() -> Any | None:
+    """Return ``wiki_studio.api`` when it offers the proposal gate (wiki-studio >= 0.3), else ``None``.
+
+    ``None`` means absent or an older wiki-studio without the gate, where the
+    direct writer is the supported fallback. A present but broken package
+    raises :class:`GateError`: the validator is installed, so its failure must
+    not be mistaken for its absence and let pages through unchecked.
+    """
+    try:
+        api = load_studio()
+    except LintError as exc:
+        raise GateError(str(exc)) from exc
+    if api is None or not hasattr(api, "propose") or not hasattr(api, "PageEdit"):
+        return None
+    return api
+
+
+def propose_and_promote(
+    api: Any, pages: list[GatedPage], wiki_dir: Path, project_root: Path, proposals_dir: Path, name: str
+) -> None:
+    """Write ``pages`` as one patch-set and apply it through wiki-studio's promote gate.
+
+    ``index.md`` and ``log.md`` must already exist: the gate appends to them but
+    refuses to create them. Raises :class:`GateError` on any rejection or
+    failure; wiki-studio validates before writing, so a rejected patch-set
+    leaves the wiki as it was.
+    """
+    # One append per file: wiki-studio 0.3.1 keeps only the last of several appends to the same file in a
+    # patch-set (fixed in 0.4.0, wiki-studio#18; kept while the floor is 0.3.1), so every index line goes into a
+    # single append-index edit and every log line into one append-log.
+    index_lines = [page.index_line for page in pages if page.index_line is not None]
+    log_lines = [page.log_line for page in pages if page.log_line is not None]
+    try:  # every wiki-studio call is inside the boundary, setup included, so the caller's cleanup always runs
+        from wiki_studio.paths import WikiPaths
+
+        edits = [
+            api.PageEdit(path=page.path, action="create", new_content=page.content, rationale=GATE_RATIONALE)
+            for page in pages
+        ]
+        if index_lines:
+            edits.append(
+                api.PageEdit(
+                    path="index.md",
+                    action="append-index",
+                    new_content="\n".join(index_lines),
+                    rationale=GATE_RATIONALE,
+                )
+            )
+        if log_lines:
+            edits.append(
+                api.PageEdit(
+                    path="log.md", action="append-log", new_content="\n".join(log_lines), rationale=GATE_RATIONALE
+                )
+            )
+        paths = WikiPaths.for_root(project_root, wiki_dir=wiki_dir, proposals_dir=proposals_dir)
+        proposal = api.propose(edits, paths, name=name, source="memkernel wiki_export", backend=GATE_BACKEND)
+        api.promote(proposal, paths)
+    except Exception as exc:  # any rejection or failure of the installed gate is reported, never raised raw
+        logger.warning("wiki-studio gate rejected the export to %s: %s", wiki_dir, exc)
+        raise GateError(f"wiki-studio gate rejected the export: {exc}") from exc

memkernel-0.5.0/src/memkernel/wiki/sync.py

@@ -0,0 +1,425 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""Export long-term memories to wiki pages and import wiki pages as memories.
+
+Direction 1 — ``WikiExporter`` ("compile"): every long-term memory that has no
+wiki page yet becomes a *draft* page in the matching section, with the page
+sections the wiki schema requires. The exporter is deliberately LLM-free: it
+produces a reviewable draft (the memory content in the primary section,
+placeholders elsewhere) and leaves synthesis to the agent or curator, mirroring
+the proposal → promote flow of ``code-copilot-team/scripts/wiki``.
+
+Direction 2 — ``WikiImporter`` ("index"): every curated page becomes a
+long-term memory (type by page_type) so ``recall`` can find it. Re-running the
+importer is idempotent: unchanged pages dedup on content hash, changed pages
+supersede their previous version.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from memkernel.core.models import MemoryTier, MemoryType
+from memkernel.wiki.pages import WikiPage, parse_page, render_page, slugify
+from memkernel.wiki.studio import (
+    GatedPage,
+    GateError,
+    LintError,
+    LintSummary,
+    gate_available,
+    lint_wiki,
+    load_studio,
+    propose_and_promote,
+)
+
+if TYPE_CHECKING:
+    from memkernel.core.models import Memory
+    from memkernel.core.services import MemoryService
+
+logger = logging.getLogger(__name__)
+
+WIKI_TAG = "wiki"
+INDEX_FILE = "index.md"
+LOG_FILE = "log.md"
+DEFAULT_PROPOSALS_SUBDIR = Path(".memkernel") / "wiki-proposals"
+
+# MemoryType -> (page_type, directory). CODE is not exported: code lives in the
+# repo. DOCUMENT is not exported either: documents are sources, not wiki pages.
+EXPORT_MAP: dict[MemoryType, tuple[str, str]] = {
+    MemoryType.DECISION: ("decision", "decisions"),
+    MemoryType.CONVENTION: ("concept", "concepts"),
+    MemoryType.FACT: ("concept", "concepts"),
+    MemoryType.PROCEDURE: ("workflow", "workflows"),
+}
+
+# page_type -> MemoryType for import. Pages without a mapping are skipped.
+IMPORT_MAP: dict[str, MemoryType] = {
+    "decision": MemoryType.DECISION,
+    "concept": MemoryType.FACT,
+    "overview": MemoryType.FACT,
+    "glossary": MemoryType.FACT,
+    "incident": MemoryType.FACT,
+    "open-question": MemoryType.FACT,
+    "workflow": MemoryType.PROCEDURE,
+    "playbook": MemoryType.PROCEDURE,
+}
+
+# Required H2 sections per page type (first one receives the memory content).
+PAGE_SECTIONS: dict[str, list[str]] = {
+    "decision": ["Decision", "Context", "Alternatives considered", "Consequences"],
+    "concept": ["Summary", "Key ideas", "Where this shows up", "Related"],
+    "workflow": ["When to use this", "Steps", "Verification", "Related"],
+}
+
+PLACEHOLDER = "_Not recorded in memory — curate before marking this page stable._"
+
+
+def _today() -> str:
+    return datetime.now(UTC).date().isoformat()
+
+
+@dataclass
+class ExportReport:
+    """Outcome of an export run.
+
+    ``lint`` holds wiki-studio's lint and health results for the **whole wiki**
+    as it is after the export (curated pages included), or ``None`` when the
+    ``memkernel[wiki]`` extra is not installed or its lint pass failed; in the
+    latter case ``lint_error`` says why. The written files are the same in
+    every case.
+    """
+
+    written: list[str] = field(default_factory=list)
+    skipped: int = 0
+    lint: LintSummary | None = None
+    lint_error: str | None = None
+    gated: bool = False  # the pages went through wiki-studio's promote gate
+    gate_error: str | None = None  # the gate rejected the export; nothing was written
+
+
+@dataclass
+class ImportReport:
+    """Outcome of an import run."""
+
+    imported: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+
+
+class WikiExporter:
+    """Compile long-term memories into draft wiki pages under ``wiki_dir``."""
+
+    def __init__(
+        self,
+        service: MemoryService,
+        wiki_dir: Path,
+        project_root: Path | None = None,
+        proposals_dir: Path | None = None,
+    ) -> None:
+        self._service = service
+        self._wiki_dir = Path(wiki_dir)
+        # The root ``path:`` sources resolve against; memkernel's project root when the tool passes it.
+        self._project_root = Path(project_root) if project_root is not None else self._wiki_dir.parent
+        # An explicit proposals directory is a request for the gate (FR-006): its absence is then worth a warning.
+        self._proposals_requested = proposals_dir is not None
+        self._proposals_dir = (
+            Path(proposals_dir) if proposals_dir is not None else self._project_root / DEFAULT_PROPOSALS_SUBDIR
+        )
+
+    def export(self, memories: list[Memory] | None = None, update_index: bool = True) -> ExportReport:
+        """Write one page per exportable memory that is not already a wiki page.
+
+        Memories that came from the wiki (tagged ``wiki``), chunk records, or
+        memories a newer memory supersedes (``superseded_by`` set) are skipped. Existing pages with
+        the same slug are left untouched: the wiki, once written, is curated
+        by humans/agents, not overwritten by the store. With the ``memkernel[wiki]``
+        extra installed the report carries wiki-studio's lint and health findings
+        for the whole wiki as it is after the export; a lint failure is reported
+        in ``lint_error`` and never fails the export.
+        """
+        report = ExportReport()
+        candidates = memories if memories is not None else self._service.list_memories(tier=MemoryTier.LONG_TERM)
+        planned: list[tuple[str, WikiPage]] = []
+        for memory in candidates:
+            mapping = EXPORT_MAP.get(memory.type)
+            if mapping is None or WIKI_TAG in memory.tags or memory.superseded_by or memory.chunk_refs:
+                report.skipped += 1
+                continue
+            page_type, directory = mapping
+            page = self._page_for(memory, page_type)
+            rel = f"{directory}/{page.slug}.md"
+            if (self._wiki_dir / rel).exists() or any(r == rel for r, _ in planned):
+                report.skipped += 1
+                continue
+            planned.append((rel, page))
+
+        # Pages without index entries are orphans, which the gate rejects by design; update_index=False
+        # therefore always takes the direct writer.
+        api = None
+        try:
+            api = gate_available() if planned and update_index else None
+        except GateError as exc:  # wiki-studio installed but broken: never fall back to unchecked writes
+            report.gate_error = str(exc)
+            report.skipped += len(planned)
+            planned = []
+        if self._proposals_requested and api is None and report.gate_error is None:
+            if planned and not update_index:
+                logger.warning(
+                    "wiki gate requested (proposals directory set) but update_index=False bypasses it: "
+                    "pages without index entries cannot pass the gate; writing directly"
+                )
+            else:
+                # logs once that the requested gate is unavailable; a broken installation with nothing
+                # to write is reported by the lint pass below
+                with contextlib.suppress(LintError):
+                    load_studio(require_studio=True)
+        if api is not None:
+            self._export_gated(api, planned, report)
+        else:
+            for rel, page in planned:
+                target = self._wiki_dir / rel
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(render_page(page), encoding="utf-8")
+                report.written.append(rel)
+                if update_index:
+                    self._append_index(rel, page)
+                    self._append_log(page, "created")
+        try:
+            report.lint = lint_wiki(self._wiki_dir, self._project_root)
+        except LintError as exc:
+            report.lint_error = str(exc)
+        return report
+
+    def _export_gated(self, api: object, planned: list[tuple[str, WikiPage]], report: ExportReport) -> None:
+        """Scaffold first (the gate cannot create index.md or log.md), then every page through propose + promote."""
+        index_path = self._wiki_dir / INDEX_FILE
+        try:
+            index_text = index_path.read_text(encoding="utf-8") if index_path.exists() else ""
+        except (OSError, UnicodeDecodeError) as exc:  # reported like every other gate failure, nothing written
+            report.gate_error = f"could not read {INDEX_FILE}: {exc}"
+            report.skipped += len(planned)
+            logger.warning("wiki export to %s failed: %s", self._wiki_dir, report.gate_error)
+            return
+        pages = [
+            GatedPage(
+                path=rel,
+                content=render_page(page),
+                # same rule as the direct writer: no second index entry for a page already linked
+                index_line=self._index_line(rel, page) if f"]({rel})" not in index_text else None,
+                log_line=self._log_line(page, "created"),
+            )
+            for rel, page in planned
+        ]
+        name = f"memkernel-export-{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}"
+        snapshot: _WikiSnapshot | None = None
+        try:
+            snapshot = _WikiSnapshot.take(self._wiki_dir)
+            self._ensure_scaffold()
+            propose_and_promote(api, pages, self._wiki_dir, self._project_root, self._proposals_dir, name)
+        except (GateError, OSError) as exc:
+            message = str(exc) if isinstance(exc, GateError) else f"the wiki could not be prepared for the gate: {exc}"
+            if isinstance(exc, OSError):
+                logger.warning("wiki export to %s failed: %s", self._wiki_dir, message)
+            problems = snapshot.restore() if snapshot is not None else []
+            if problems:
+                message += "; the wiki could not be fully restored: " + "; ".join(problems)
+                logger.warning("wiki export to %s left changes behind: %s", self._wiki_dir, "; ".join(problems))
+            report.gate_error = message
+            report.skipped += len(pages)
+            return
+        report.gated = True
+        report.written.extend(page.path for page in pages)
+
+    def _ensure_scaffold(self) -> None:
+        self._wiki_dir.mkdir(parents=True, exist_ok=True)
+        for name, text in ((INDEX_FILE, _index_scaffold()), (LOG_FILE, _log_scaffold())):
+            path = self._wiki_dir / name
+            if not path.exists():
+                path.write_text(text, encoding="utf-8")
+
+    @staticmethod
+    def _index_line(rel: str, page: WikiPage) -> str:
+        return f"- [{page.title}]({rel}) — draft compiled from memkernel ({page.extra.get('memory_type', '')})."
+
+    @staticmethod
+    def _log_line(page: WikiPage, verb: str) -> str:
+        ref = page.extra.get("memkernel_ref", "")
+        return f"- {_today()} — {verb} `{page.slug}` ({page.page_type}): compiled from memkernel {ref}"
+
+    def _page_for(self, memory: Memory, page_type: str) -> WikiPage:
+        title = memory.content.strip().splitlines()[0][:80] if memory.content.strip() else memory.ref_id
+        slug = slugify(title)
+        sections = PAGE_SECTIONS[page_type]
+        body_lines = [f"# {title}", ""]
+        for i, heading in enumerate(sections):
+            body_lines.append(f"## {heading}")
+            body_lines.append("")
+            body_lines.append(memory.content.strip() if i == 0 else PLACEHOLDER)
+            body_lines.append("")
+        sources: list[dict[str, str]] = [
+            {"url": f"memkernel://{memory.project_id}/{memory.ref_id}", "retrieved": _today()}
+        ]
+        if memory.source:
+            sources.append({"path": memory.source})
+        return WikiPage(
+            page_type=page_type,
+            slug=slug,
+            title=title,
+            status="draft",
+            last_reviewed=_today(),
+            sources=sources,
+            body="\n".join(body_lines),
+            extra={"memkernel_ref": memory.ref_id, "memory_type": memory.type.value},
+        )
+
+    def _append_index(self, rel: str, page: WikiPage) -> None:
+        index = self._wiki_dir / INDEX_FILE
+        if not index.exists():
+            index.write_text(_index_scaffold(), encoding="utf-8")
+        text = index.read_text(encoding="utf-8")
+        if f"]({rel})" in text:
+            return
+        if not text.endswith("\n"):
+            text += "\n"
+        index.write_text(text + self._index_line(rel, page) + "\n", encoding="utf-8")
+
+    def _append_log(self, page: WikiPage, verb: str) -> None:
+        log = self._wiki_dir / LOG_FILE
+        if not log.exists():
+            log.write_text(_log_scaffold(), encoding="utf-8")
+        with log.open("a", encoding="utf-8") as fh:
+            fh.write(self._log_line(page, verb) + "\n")
+
+
+@dataclass
+class _WikiSnapshot:
+    """Every file a gated export can write, taken before it starts, so a failure restores exactly that.
+
+    wiki-studio's promote before 0.4.1 (gosha70/wiki-studio#21) rolls back only
+    the writes that completed, and only on ``OSError``: a page or ``index.md`` whose
+    write failed part-way stays as it was left. Its commit step writes every ``*.md`` of the staged wiki that
+    differs from the live one, plus ``.audit/**/plan.json``, so the snapshot holds
+    all of those as bytes (not only the files memkernel's edits change), and any
+    such file that appears during the export is removed again. The cost is one
+    read of every page per gated export, which is negligible at the size of a
+    project wiki (tens to hundreds of pages).
+    """
+
+    wiki_dir: Path
+    files: dict[Path, bytes]
+    dirs: set[Path]  # directories that existed, the wiki directory included when it did
+
+    @classmethod
+    def take(cls, wiki_dir: Path) -> _WikiSnapshot:
+        files = {path: path.read_bytes() for path in cls._tracked(wiki_dir)}
+        dirs = {path for path in wiki_dir.rglob("*") if path.is_dir()} if wiki_dir.is_dir() else set()
+        if wiki_dir.is_dir():
+            dirs.add(wiki_dir)
+        return cls(wiki_dir, files, dirs)
+
+    @staticmethod
+    def _tracked(wiki_dir: Path) -> list[Path]:
+        if not wiki_dir.is_dir():
+            return []
+        return [
+            path
+            for path in wiki_dir.rglob("*")
+            if path.is_file() and (path.suffix == ".md" or (path.name == "plan.json" and ".audit" in path.parts))
+        ]
+
+    def restore(self) -> list[str]:
+        """Put every tracked file back; returns what could not be restored (empty = the wiki is as it was)."""
+        problems: list[str] = []
+        for path in self._tracked(self.wiki_dir):
+            if path not in self.files:
+                try:
+                    path.unlink()
+                except OSError as exc:
+                    problems.append(self._problem(path, exc))
+        for path, original in self.files.items():
+            try:
+                if not path.is_file() or path.read_bytes() != original:
+                    path.parent.mkdir(parents=True, exist_ok=True)
+                    path.write_bytes(original)
+            except OSError as exc:
+                problems.append(self._problem(path, exc))
+        created = [path for path in self.wiki_dir.rglob("*") if path.is_dir() and path not in self.dirs]
+        if self.wiki_dir.is_dir() and self.wiki_dir not in self.dirs:
+            created.append(self.wiki_dir)
+        for directory in sorted(created, key=lambda d: len(d.parts), reverse=True):
+            try:
+                if not any(directory.iterdir()):
+                    directory.rmdir()
+            except OSError as exc:
+                problems.append(self._problem(directory, exc))
+        return problems
+
+    def _problem(self, path: Path, exc: OSError) -> str:
+        return f"{path.relative_to(self.wiki_dir.parent).as_posix()}: {exc}"
+
+
+def _index_scaffold() -> str:
+    return (
+        "---\npage_type: index\nslug: index\ntitle: Wiki Index\nstatus: draft\n"
+        f"last_reviewed: {_today()}\n---\n\n# Wiki Index\n\n## Compiled from memkernel\n\n"
+    )
+
+
+def _log_scaffold() -> str:
+    return (
+        "---\npage_type: log\nslug: log\ntitle: Wiki Edit Log\nstatus: draft\n"
+        f"last_reviewed: {_today()}\n---\n\n# Wiki Edit Log\n\n## Entries\n\n"
+    )
+
+
+class WikiImporter:
+    """Index curated wiki pages as long-term memories."""
+
+    def __init__(self, service: MemoryService, wiki_dir: Path) -> None:
+        self._service = service
+        self._wiki_dir = Path(wiki_dir)
+
+    def import_pages(self, session_id: str | None = None) -> ImportReport:
+        """Retain every page with a mapped page_type; return what was imported/skipped."""
+        report = ImportReport()
+        existing = {
+            self._page_tag(m): m
+            for m in self._service.list_memories(tier=MemoryTier.LONG_TERM)
+            if WIKI_TAG in m.tags and self._page_tag(m)
+        }
+        for path in sorted(self._wiki_dir.rglob("*.md")):
+            rel = path.relative_to(self._wiki_dir).as_posix()
+            if rel.startswith(("schema/", "scripts/", ".")):
+                continue
+            page = parse_page(path.read_text(encoding="utf-8"))
+            memory_type = IMPORT_MAP.get(page.page_type) if page else None
+            if page is None or memory_type is None or page.status == "deprecated":
+                report.skipped.append(rel)
+                continue
+            content = f"{page.title}\n\n{page.body}".strip()
+            tags = [WIKI_TAG, f"page:{page.slug}", f"page_type:{page.page_type}"]
+            previous = existing.get(f"page:{page.slug}")
+            supersedes = previous.ref_id if previous is not None and previous.content != content else None
+            self._service.retain(
+                content=content,
+                type=memory_type,
+                session_id=session_id,
+                source=rel,
+                importance=0.9 if page.status == "stable" else 0.7,
+                tags=tags,
+                supersedes=supersedes,
+            )
+            report.imported.append(rel)
+        return report
+
+    @staticmethod
+    def _page_tag(memory: Memory) -> str:
+        for tag in memory.tags:
+            if tag.startswith("page:"):
+                return tag
+        return ""

memkernel-0.4.1/src/memkernel/wiki/sync.py

@@ -1,228 +0,0 @@
-# Copyright (c) 2026 EGOGE
-# SPDX-License-Identifier: Apache-2.0
-"""Export long-term memories to wiki pages and import wiki pages as memories.
-
-Direction 1 — ``WikiExporter`` ("compile"): every long-term memory that has no
-wiki page yet becomes a *draft* page in the matching section, with the page
-sections the wiki schema requires. The exporter is deliberately LLM-free: it
-produces a reviewable draft (the memory content in the primary section,
-placeholders elsewhere) and leaves synthesis to the agent or curator, mirroring
-the proposal → promote flow of ``code-copilot-team/scripts/wiki``.
-
-Direction 2 — ``WikiImporter`` ("index"): every curated page becomes a
-long-term memory (type by page_type) so ``recall`` can find it. Re-running the
-importer is idempotent: unchanged pages dedup on content hash, changed pages
-supersede their previous version.
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from memkernel.core.models import MemoryTier, MemoryType
-from memkernel.wiki.pages import WikiPage, parse_page, render_page, slugify
-
-if TYPE_CHECKING:
-    from memkernel.core.models import Memory
-    from memkernel.core.services import MemoryService
-
-logger = logging.getLogger(__name__)
-
-WIKI_TAG = "wiki"
-INDEX_FILE = "index.md"
-LOG_FILE = "log.md"
-
-# MemoryType -> (page_type, directory). CODE is not exported: code lives in the
-# repo. DOCUMENT is not exported either: documents are sources, not wiki pages.
-EXPORT_MAP: dict[MemoryType, tuple[str, str]] = {
-    MemoryType.DECISION: ("decision", "decisions"),
-    MemoryType.CONVENTION: ("concept", "concepts"),
-    MemoryType.FACT: ("concept", "concepts"),
-    MemoryType.PROCEDURE: ("workflow", "workflows"),
-}
-
-# page_type -> MemoryType for import. Pages without a mapping are skipped.
-IMPORT_MAP: dict[str, MemoryType] = {
-    "decision": MemoryType.DECISION,
-    "concept": MemoryType.FACT,
-    "overview": MemoryType.FACT,
-    "glossary": MemoryType.FACT,
-    "incident": MemoryType.FACT,
-    "open-question": MemoryType.FACT,
-    "workflow": MemoryType.PROCEDURE,
-    "playbook": MemoryType.PROCEDURE,
-}
-
-# Required H2 sections per page type (first one receives the memory content).
-PAGE_SECTIONS: dict[str, list[str]] = {
-    "decision": ["Decision", "Context", "Alternatives considered", "Consequences"],
-    "concept": ["Summary", "Key ideas", "Where this shows up", "Related"],
-    "workflow": ["When to use this", "Steps", "Verification", "Related"],
-}
-
-PLACEHOLDER = "_Not recorded in memory — curate before marking this page stable._"
-
-
-def _today() -> str:
-    return datetime.now(UTC).date().isoformat()
-
-
-@dataclass
-class ExportReport:
-    """Outcome of an export run."""
-
-    written: list[str] = field(default_factory=list)
-    skipped: int = 0
-
-
-@dataclass
-class ImportReport:
-    """Outcome of an import run."""
-
-    imported: list[str] = field(default_factory=list)
-    skipped: list[str] = field(default_factory=list)
-
-
-class WikiExporter:
-    """Compile long-term memories into draft wiki pages under ``wiki_dir``."""
-
-    def __init__(self, service: MemoryService, wiki_dir: Path) -> None:
-        self._service = service
-        self._wiki_dir = Path(wiki_dir)
-
-    def export(self, memories: list[Memory] | None = None, update_index: bool = True) -> ExportReport:
-        """Write one page per exportable memory that is not already a wiki page.
-
-        Memories that came from the wiki (tagged ``wiki``), chunk records, or
-        memories a newer memory supersedes (``superseded_by`` set) are skipped. Existing pages with
-        the same slug are left untouched: the wiki, once written, is curated
-        by humans/agents, not overwritten by the store.
-        """
-        report = ExportReport()
-        candidates = memories if memories is not None else self._service.list_memories(tier=MemoryTier.LONG_TERM)
-        for memory in candidates:
-            mapping = EXPORT_MAP.get(memory.type)
-            if mapping is None or WIKI_TAG in memory.tags or memory.superseded_by or memory.chunk_refs:
-                report.skipped += 1
-                continue
-            page_type, directory = mapping
-            page = self._page_for(memory, page_type)
-            target = self._wiki_dir / directory / f"{page.slug}.md"
-            if target.exists():
-                report.skipped += 1
-                continue
-            target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(render_page(page), encoding="utf-8")
-            rel = f"{directory}/{page.slug}.md"
-            report.written.append(rel)
-            if update_index:
-                self._append_index(rel, page)
-                self._append_log(page, "created")
-        return report
-
-    def _page_for(self, memory: Memory, page_type: str) -> WikiPage:
-        title = memory.content.strip().splitlines()[0][:80] if memory.content.strip() else memory.ref_id
-        slug = slugify(title)
-        sections = PAGE_SECTIONS[page_type]
-        body_lines = [f"# {title}", ""]
-        for i, heading in enumerate(sections):
-            body_lines.append(f"## {heading}")
-            body_lines.append("")
-            body_lines.append(memory.content.strip() if i == 0 else PLACEHOLDER)
-            body_lines.append("")
-        sources: list[dict[str, str]] = [
-            {"url": f"memkernel://{memory.project_id}/{memory.ref_id}", "retrieved": _today()}
-        ]
-        if memory.source:
-            sources.append({"path": memory.source})
-        return WikiPage(
-            page_type=page_type,
-            slug=slug,
-            title=title,
-            status="draft",
-            last_reviewed=_today(),
-            sources=sources,
-            body="\n".join(body_lines),
-            extra={"memkernel_ref": memory.ref_id, "memory_type": memory.type.value},
-        )
-
-    def _append_index(self, rel: str, page: WikiPage) -> None:
-        index = self._wiki_dir / INDEX_FILE
-        line = f"- [{page.title}]({rel}) — draft compiled from memkernel ({page.extra.get('memory_type', '')})."
-        if not index.exists():
-            index.write_text(
-                "---\npage_type: index\nslug: index\ntitle: Wiki Index\nstatus: draft\n"
-                f"last_reviewed: {_today()}\n---\n\n# Wiki Index\n\n## Compiled from memkernel\n\n",
-                encoding="utf-8",
-            )
-        text = index.read_text(encoding="utf-8")
-        if f"]({rel})" in text:
-            return
-        if not text.endswith("\n"):
-            text += "\n"
-        index.write_text(text + line + "\n", encoding="utf-8")
-
-    def _append_log(self, page: WikiPage, verb: str) -> None:
-        log = self._wiki_dir / LOG_FILE
-        if not log.exists():
-            log.write_text(
-                "---\npage_type: log\nslug: log\ntitle: Wiki Edit Log\nstatus: draft\n"
-                f"last_reviewed: {_today()}\n---\n\n# Wiki Edit Log\n\n## Entries\n\n",
-                encoding="utf-8",
-            )
-        ref = page.extra.get("memkernel_ref", "")
-        entry = f"- {_today()} — {verb} `{page.slug}` ({page.page_type}): compiled from memkernel {ref}\n"
-        with log.open("a", encoding="utf-8") as fh:
-            fh.write(entry)
-
-
-class WikiImporter:
-    """Index curated wiki pages as long-term memories."""
-
-    def __init__(self, service: MemoryService, wiki_dir: Path) -> None:
-        self._service = service
-        self._wiki_dir = Path(wiki_dir)
-
-    def import_pages(self, session_id: str | None = None) -> ImportReport:
-        """Retain every page with a mapped page_type; return what was imported/skipped."""
-        report = ImportReport()
-        existing = {
-            self._page_tag(m): m
-            for m in self._service.list_memories(tier=MemoryTier.LONG_TERM)
-            if WIKI_TAG in m.tags and self._page_tag(m)
-        }
-        for path in sorted(self._wiki_dir.rglob("*.md")):
-            rel = path.relative_to(self._wiki_dir).as_posix()
-            if rel.startswith(("schema/", "scripts/", ".")):
-                continue
-            page = parse_page(path.read_text(encoding="utf-8"))
-            memory_type = IMPORT_MAP.get(page.page_type) if page else None
-            if page is None or memory_type is None or page.status == "deprecated":
-                report.skipped.append(rel)
-                continue
-            content = f"{page.title}\n\n{page.body}".strip()
-            tags = [WIKI_TAG, f"page:{page.slug}", f"page_type:{page.page_type}"]
-            previous = existing.get(f"page:{page.slug}")
-            supersedes = previous.ref_id if previous is not None and previous.content != content else None
-            self._service.retain(
-                content=content,
-                type=memory_type,
-                session_id=session_id,
-                source=rel,
-                importance=0.9 if page.status == "stable" else 0.7,
-                tags=tags,
-                supersedes=supersedes,
-            )
-            report.imported.append(rel)
-        return report
-
-    @staticmethod
-    def _page_tag(memory: Memory) -> str:
-        for tag in memory.tags:
-            if tag.startswith("page:"):
-                return tag
-        return ""