memkernel 0.4.0__tar.gz → 0.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memkernel
-Version: 0.4.0
+Version: 0.4.1
 Summary: Code-aware memory server for AI coding copilots
 License: Apache-2.0
 License-File: LICENSE
@@ -47,6 +47,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). 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.
+
 ---
 
 ## Requirements
@@ -221,6 +239,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 |
 |----------|---------|-------------|
@@ -331,7 +351,7 @@ 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) (`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).
 
 ### Revalidation and store health
 
@@ -411,7 +431,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.4.1}/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). 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.
+
 ---
 
 ## Requirements
@@ -192,6 +210,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 |
 |----------|---------|-------------|
@@ -302,7 +322,7 @@ 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) (`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).
 
 ### Revalidation and store health
 
@@ -382,7 +402,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.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "memkernel"
-version = "0.4.0"
+version = "0.4.1"
 description = "Code-aware memory server for AI coding copilots"
 authors = ["EGOGE"]
 license = "Apache-2.0"
@@ -40,6 +40,7 @@ ruff = ">=0.9"
 mypy = ">=1.13"
 httpx = ">=0.27"
 pip-audit = "^2.10.0"
+wiki-studio = ">=0.1,<1"
 
 [build-system]
 requires = ["poetry-core"]

{memkernel-0.4.0 → memkernel-0.4.1}/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.4.1"

memkernel-0.4.1/src/memkernel/config.py

@@ -0,0 +1,129 @@
+# 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 = ""
+
+    # 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/src/memkernel/config.py

@@ -1,70 +0,0 @@
-# Copyright (c) 2026 EGOGE
-# SPDX-License-Identifier: Apache-2.0
-"""MemKernel configuration via environment variables."""
-
-from __future__ import annotations
-
-from typing import Literal
-
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class MemKernelSettings(BaseSettings):
-    """All settings are configurable via MEMKERNEL_ prefixed env vars."""
-
-    model_config = SettingsConfigDict(env_prefix="MEMKERNEL_", env_file=".env")
-
-    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 = ""
-
-    # Server
-    transport: Literal["stdio", "streamable-http"] = "stdio"
-    host: str = "127.0.0.1"
-    port: int = 8765