memkernel 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memkernel
-Version: 0.4.0
+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
@@ -47,6 +49,24 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 
 **Tiered memory (0.2)**: memories live in three tiers with different persistence rules — *working* (the current task, hours), *short-term* (episodes and observations, decays unless recalled) and *long-term* (decisions, conventions, facts, procedures, code; never decays, replaced by supersession). Recall ranks by relevance, recency and importance; `consolidate` and `promote` move what proved useful into long-term memory; an LLM-wiki bridge keeps a human-readable, git-versioned copy of long-term knowledge. Design: [`docs/architecture/memory-tiers.md`](docs/architecture/memory-tiers.md).
 
+## What MemKernel is, and what it is not
+
+**It is:**
+
+- **Persistent memory for a coding agent.** What the agent retains survives context compaction and the end of a session, in a local ChromaDB store per project.
+- **Explicit.** The agent decides what to retain (decisions, conventions, facts, code snapshots, tasks) and what to recall. The lifecycle hooks only automate the protocol around that: checkpoint before compaction, recovery after it, consolidation and revalidation at session start.
+- **Code-aware.** AST chunking, hybrid search that finds identifiers as well as meaning, and revalidation of `code` memories against the files they came from.
+- **No mandatory generative LLM.** Default retrieval uses a local sentence-transformer embedding model plus BM25 and RRF; nothing generates text inside MemKernel. `ask` with the built-in reasoner returns the best-matching chunks; synthesis is the agent's job, or an optional external reasoner's.
+
+**It is not:**
+
+- **A token optimizer or context compressor.** MemKernel does not shrink the context window, compress prompts, or lower model cost by itself. It adds tool calls and returned content to a session. Any token saving comes from the agent re-reading fewer files or documents after a resume; that is a side effect to measure, not a promise.
+- **A replacement for files, specs and git.** Progress notes, task lists and review records already carry state between sessions. MemKernel adds retrieval by meaning and identifier, tiers with decay, supersession and revalidation on top. When a file already holds everything the next session needs, expect no gain.
+- **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.
+
 ---
 
 ## Requirements
@@ -66,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:
@@ -221,6 +244,8 @@ ask(ref_id="<document ref_id>", question="Which endpoints need rate limiting?",
 ## Configuration
 
 All settings are read from environment variables with the `MEMKERNEL_` prefix, or from a `.env` file.
+Entries in `.env` without the prefix (keys for other tools) are ignored; a `MEMKERNEL_` key that matches no
+setting is logged as a warning at startup.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -252,6 +277,7 @@ All settings are read from environment variables with the `MEMKERNEL_` prefix, o
 | `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 |
@@ -331,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. Rationale and the proposed standalone `ai-wiki` repo: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
+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
 
@@ -411,7 +441,7 @@ MemKernel is the memory component of a small family of projects by the same auth
 
 | Project | Role | Relationship |
 |---|---|---|
-| [ai-wiki](https://github.com/gosha70/ai-wiki) | LLM-maintained markdown wiki (ingest / promote / query / lint) | the human-readable form of long-term memory; `wiki_export` / `wiki_import` speak its page schema (ADR-008) |
+| [wiki-studio](https://github.com/gosha70/wiki-studio) | LLM-wiki maintainer (ingest / promote / query / lint / audit), stdlib-only | the human-readable form of long-term memory; `wiki_export` / `wiki_import` speak its page schema (ADR-008), and CI lints exporter output with it |
 | [rlm-studio](https://github.com/gosha70/rlm-studio) | Recursive Language Models workbench: Direct / RAG / RLM / auto over large documents | the document layer behind `document` memories and the `ask()` tool (`MEMKERNEL_REASONER=rlmstudio`, ADR-009) |
 | [code-copilot-team](https://github.com/gosha70/code-copilot-team) | Enforceable harness configuration for Claude Code, Pi and other copilots | consumes MemKernel through MCP and hooks |
 | [haa](https://github.com/gosha70/haa) | Home-built AI coding harness, future component assembler | consumes MemKernel in-process through `build_service()` |

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

@@ -18,6 +18,24 @@ MemKernel gives Claude Code (and any MCP-compatible copilot) persistent memory a
 
 **Tiered memory (0.2)**: memories live in three tiers with different persistence rules — *working* (the current task, hours), *short-term* (episodes and observations, decays unless recalled) and *long-term* (decisions, conventions, facts, procedures, code; never decays, replaced by supersession). Recall ranks by relevance, recency and importance; `consolidate` and `promote` move what proved useful into long-term memory; an LLM-wiki bridge keeps a human-readable, git-versioned copy of long-term knowledge. Design: [`docs/architecture/memory-tiers.md`](docs/architecture/memory-tiers.md).
 
+## What MemKernel is, and what it is not
+
+**It is:**
+
+- **Persistent memory for a coding agent.** What the agent retains survives context compaction and the end of a session, in a local ChromaDB store per project.
+- **Explicit.** The agent decides what to retain (decisions, conventions, facts, code snapshots, tasks) and what to recall. The lifecycle hooks only automate the protocol around that: checkpoint before compaction, recovery after it, consolidation and revalidation at session start.
+- **Code-aware.** AST chunking, hybrid search that finds identifiers as well as meaning, and revalidation of `code` memories against the files they came from.
+- **No mandatory generative LLM.** Default retrieval uses a local sentence-transformer embedding model plus BM25 and RRF; nothing generates text inside MemKernel. `ask` with the built-in reasoner returns the best-matching chunks; synthesis is the agent's job, or an optional external reasoner's.
+
+**It is not:**
+
+- **A token optimizer or context compressor.** MemKernel does not shrink the context window, compress prompts, or lower model cost by itself. It adds tool calls and returned content to a session. Any token saving comes from the agent re-reading fewer files or documents after a resume; that is a side effect to measure, not a promise.
+- **A replacement for files, specs and git.** Progress notes, task lists and review records already carry state between sessions. MemKernel adds retrieval by meaning and identifier, tiers with decay, supersession and revalidation on top. When a file already holds everything the next session needs, expect no gain.
+- **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.
+
 ---
 
 ## Requirements
@@ -37,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:
@@ -192,6 +213,8 @@ ask(ref_id="<document ref_id>", question="Which endpoints need rate limiting?",
 ## Configuration
 
 All settings are read from environment variables with the `MEMKERNEL_` prefix, or from a `.env` file.
+Entries in `.env` without the prefix (keys for other tools) are ignored; a `MEMKERNEL_` key that matches no
+setting is logged as a warning at startup.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -223,6 +246,7 @@ All settings are read from environment variables with the `MEMKERNEL_` prefix, o
 | `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 |
@@ -302,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. Rationale and the proposed standalone `ai-wiki` repo: [`docs/adr/ADR-008-llm-wiki-as-semantic-layer.md`](docs/adr/ADR-008-llm-wiki-as-semantic-layer.md).
+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
 
@@ -382,7 +410,7 @@ MemKernel is the memory component of a small family of projects by the same auth
 
 | Project | Role | Relationship |
 |---|---|---|
-| [ai-wiki](https://github.com/gosha70/ai-wiki) | LLM-maintained markdown wiki (ingest / promote / query / lint) | the human-readable form of long-term memory; `wiki_export` / `wiki_import` speak its page schema (ADR-008) |
+| [wiki-studio](https://github.com/gosha70/wiki-studio) | LLM-wiki maintainer (ingest / promote / query / lint / audit), stdlib-only | the human-readable form of long-term memory; `wiki_export` / `wiki_import` speak its page schema (ADR-008), and CI lints exporter output with it |
 | [rlm-studio](https://github.com/gosha70/rlm-studio) | Recursive Language Models workbench: Direct / RAG / RLM / auto over large documents | the document layer behind `document` memories and the `ask()` tool (`MEMKERNEL_REASONER=rlmstudio`, ADR-009) |
 | [code-copilot-team](https://github.com/gosha70/code-copilot-team) | Enforceable harness configuration for Claude Code, Pi and other copilots | consumes MemKernel through MCP and hooks |
 | [haa](https://github.com/gosha70/haa) | Home-built AI coding harness, future component assembler | consumes MemKernel in-process through `build_service()` |

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "memkernel"
-version = "0.4.0"
+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,6 +45,7 @@ ruff = ">=0.9"
 mypy = ">=1.13"
 httpx = ">=0.27"
 pip-audit = "^2.10.0"
+wiki-studio = ">=0.3.1,<1"
 
 [build-system]
 requires = ["poetry-core"]

{memkernel-0.4.0 → 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.0"
+__version__ = "0.5.0"

memkernel-0.5.0/src/memkernel/config.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""MemKernel configuration via environment variables."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic_settings import BaseSettings, EnvSettingsSource, PydanticBaseSettingsSource, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from pydantic.fields import FieldInfo
+
+logger = logging.getLogger(__name__)
+
+ENV_PREFIX = "MEMKERNEL_"
+ENV_FILE = ".env"
+
+
+class MemKernelSettings(BaseSettings):
+    """All settings are configurable via MEMKERNEL_ prefixed env vars."""
+
+    # Unknown keys stay forbidden (constructor typos raise), but the .env source
+    # is filtered to known settings: a project .env usually holds keys for other
+    # tools and must not stop the server from starting (issue #15). Misspelled
+    # MEMKERNEL_ keys are reported by settings_customise_sources().
+    model_config = SettingsConfigDict(env_prefix=ENV_PREFIX, env_file=ENV_FILE)
+
+    project_id: str = "default"
+    default_session_id: str = "default"
+
+    # ChromaDB
+    chroma_persist_path: str = ".memkernel/chroma"
+    chroma_collection_prefix: str = "memkernel"
+
+    # Embedding
+    embedding_model: str = "all-MiniLM-L6-v2"
+    embedding_dimension: int = 384
+
+    # Retrieval
+    search_top_k: int = 5
+    rrf_k: int = 60
+    preview_length: int = 200
+
+    # Chunking
+    chunk_size: int = 1500  # max chars per chunk
+    chunk_overlap: int = 200  # char overlap between token chunks (fallback only)
+
+    # Documents and ask() (ADR-009)
+    document_store: Literal["local"] = "local"  # where `document` bodies live
+    document_summary_chars: int = 1000  # characters of the body kept in the document's summary record
+    reasoner: Literal["local", "rlmstudio"] = "local"  # ReasonerPort behind ask(); falls back to local
+    ask_top_k: int = 5  # chunks the local reasoner returns per ask()
+
+    # Sources, revalidation and store health (0.4)
+    project_root: str = "."  # relative `source` paths resolve under this directory; nothing outside it is read
+    health_duplicate_threshold: float = (
+        0.95  # cosine similarity in [0, 1] from which two long-term memories are near-duplicates
+    )
+    health_duplicate_limit: int = 500  # most recent long-term memories checked for near-duplicates
+    health_report_limit: int = 20  # items listed per health category
+
+    # Lifecycle / decay (see docs/architecture/memory-tiers.md)
+    episode_ttl_days: int = 30  # base TTL for short-term `episode` memories
+    observation_ttl_days: int = 7  # base TTL for short-term `observation` memories
+    task_ttl_hours: int = 24  # base TTL for working-memory `task` records
+    access_boost: float = 0.5  # each recall extends TTL by this fraction of the base TTL
+    recency_half_life_days: float = 7.0  # recency decay half-life for short-term memories
+
+    # Recall scoring: final = w_relevance * fused + w_recency * recency + w_importance * importance
+    recall_weight_relevance: float = 1.0
+    recall_weight_recency: float = 0.3
+    recall_weight_importance: float = 0.3
+
+    # 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"
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Default source order with the .env source limited to known settings.
+
+        Warns about MEMKERNEL_ keys in the environment or in .env that match no setting.
+        """
+        for source, origin in ((env_settings, "the environment"), (dotenv_settings, ENV_FILE)):
+            for key in unknown_prefixed_keys(settings_cls, source):
+                logger.warning(
+                    "memkernel: unknown setting %s in %s is ignored; check the spelling against the README", key, origin
+                )
+        return init_settings, env_settings, KnownFieldsOnly(dotenv_settings), file_secret_settings
+
+
+class KnownFieldsOnly(PydanticBaseSettingsSource):
+    """Pass through only the values of ``inner`` that belong to a settings field."""
+
+    def __init__(self, inner: PydanticBaseSettingsSource) -> None:
+        super().__init__(inner.settings_cls)
+        self._inner = inner
+
+    def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
+        return self._inner.get_field_value(field, field_name)
+
+    def __call__(self) -> dict[str, Any]:
+        return {key: value for key, value in self._inner().items() if key in self.settings_cls.model_fields}
+
+
+def unknown_prefixed_keys(settings_cls: type[BaseSettings], source: PydanticBaseSettingsSource) -> list[str]:
+    """Return the MEMKERNEL_ keys ``source`` holds that are not fields of ``settings_cls``, upper-cased."""
+    if not isinstance(source, EnvSettingsSource):
+        return []
+    prefix = ENV_PREFIX.lower()  # case-insensitive sources expose lower-cased keys
+    return sorted(
+        key.upper()
+        for key in source.env_vars
+        if key.lower().startswith(prefix) and key.lower()[len(prefix) :] not in settings_cls.model_fields
+    )

{memkernel-0.4.0 → 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