memorykit 0.6.0__tar.gz → 0.7.0__tar.gz

{memorykit-0.6.0 → memorykit-0.7.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.7.0 — 2026-08-29
+
+- Make plugin-installed MCP safe and configurable in GitHub Copilot: declare
+  `stdio` explicitly and forward the operator-set
+  `CONTEXT_KIT_MEMORY_PROJECT` (or deprecated
+  `PRODUCTIVITY_SKILLS_MEMORY_PROJECT`) into the child process. The server still
+  refuses when no explicit scope is configured; prompt content cannot select
+  another project store.
+- Move MCP proposal-only and absolute-source enforcement into the provider, so
+  quoted frontmatter follows the same parser as CLI capture and policy cannot
+  drift between surfaces. Provider validation now refuses a missing or
+  non-regular evidence source instead of skipping hash verification.
+- Bound incoming JSON-RPC frames before decoding and reconcile the MCP server
+  version in packaging tests.
+- Add MCP tool safety annotations and collapse missing-source versus
+  hash-mismatch failures into one capture refusal, avoiding a path-existence
+  distinction while preserving explicit failure.
+
 ## 0.6.0 — 2026-08-09
 
 - **Package the memory contract, validator, and MCP server as `memorykit`, ready

{memorykit-0.6.0 → memorykit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: memorykit
-Version: 0.6.0
+Version: 0.7.0
 Summary: Provenance-bound durable memory: an immutable record contract, a validator, append-only review state, and a standard-library stdio MCP server. No Python dependencies; requires git on PATH.
 Project-URL: Homepage, https://github.com/mbeacom/context-kit
 Project-URL: Repository, https://github.com/mbeacom/context-kit
@@ -77,20 +77,16 @@ Installing `memory` also installs `context-handoff`, `verify`, and
 The contract, validator, and MCP server are also packaged as **`memorykit`**, a
 pure-standard-library Python package (ADR-0002, ADR-0009).
 
-> **Not on PyPI yet.** The package is publish-ready but the name has not been
-> claimed, so `pip install memorykit` does **not** currently install this — it
-> will fail, or, if someone else claims the name first, install something else
-> entirely. Until the release workflow runs, install from a clone.
-
 ```bash
-# From a clone of https://github.com/mbeacom/context-kit
-pip install ./plugins/memory      # or: uv tool install ./plugins/memory
+pip install memorykit             # or: uv tool install memorykit
 ```
 
-Once published, that becomes:
+To work from a clone instead — for contributing, or to run an unreleased
+revision:
 
 ```bash
-pip install memorykit             # or: uv tool install memorykit
+# From a clone of https://github.com/mbeacom/context-kit
+pip install ./plugins/memory      # or: uv tool install ./plugins/memory
 ```
 
 Either way that is the whole install: no bootstrap step, no plugin runtime, no
@@ -130,7 +126,8 @@ is the reverse of the `indexkit` launcher's preference, and deliberate.
 
 ## Local-only reviewed records
 
-Python 3 is the only requirement. Configure an explicit project and plugin root:
+Python 3 and Git on `PATH` are required. Configure an explicit project and
+plugin root:
 
 ```bash
 export CONTEXT_KIT_MEMORY_PROJECT=owner/repository
@@ -223,12 +220,13 @@ authoring a `memory-v1` record from a candidate stays an explicit judgment step.
 
 See [`references/session-mining.md`](skills/memory-workflows/references/session-mining.md).
 
-## MCP surface for non-plugin hosts
+## MCP surface
 
 An optional stdio MCP server exposes `memory_recall`, `memory_capture`, and
-`memory_review` so hosts that consume skills plus MCP can use durable memory
-without a plugin runtime. It is standard library only and shells out to the
-same provider, so the CLI and MCP paths cannot drift.
+`memory_review` so hosts that consume skills plus MCP can use durable memory.
+GitHub Copilot and Claude Code plugin installs discover it automatically;
+package-only hosts can launch it directly. It is standard library only and
+shells out to the same provider, so the CLI and MCP paths cannot drift.
 
 ```bash
 # From the plugin:
@@ -239,6 +237,14 @@ CONTEXT_KIT_MEMORY_PROJECT=owner/repository \
 CONTEXT_KIT_MEMORY_PROJECT=owner/repository memorykit-mcp
 ```
 
+The bundled `.mcp.json` forwards `CONTEXT_KIT_MEMORY_PROJECT` from the host
+environment into the plugin process. Set it to the current
+`owner/repository` in the Copilot project environment or before launching the
+host; do not edit Copilot's generated MCP entry. MCP capture records must use
+an absolute `source` path because plugin hosts may launch the server outside
+the active repository. The server refuses an unset project and never infers a
+repository or falls back to a global store.
+
 The surface can propose memory but **cannot activate it**: a record whose
 frontmatter is not `review: proposed` is refused, and proposals stay out of
 active recall until promoted with the append-only `record-state` CLI.
@@ -270,7 +276,7 @@ explicit command there.
 | `/review-memory` | Review freshness, conflicts, and consolidation proposals. |
 | `/archive-handoff` | Explicitly preserve a validated handoff as historical memory. |
 | `memory-provider.py` | Launcher for the `memorykit` provider: stdlib validator, local store, MemPalace adapter, and hook dispatcher. |
-| `src/memorykit/` | The packaged engine (`memorykit`, not yet on PyPI): contract, validator, provider, MCP server. |
+| `src/memorykit/` | The packaged `memorykit` engine: contract, validator, provider, MCP server. |
 
 ## Safety boundaries
 

{memorykit-0.6.0 → memorykit-0.7.0}/README.md

@@ -34,20 +34,16 @@ Installing `memory` also installs `context-handoff`, `verify`, and
 The contract, validator, and MCP server are also packaged as **`memorykit`**, a
 pure-standard-library Python package (ADR-0002, ADR-0009).
 
-> **Not on PyPI yet.** The package is publish-ready but the name has not been
-> claimed, so `pip install memorykit` does **not** currently install this — it
-> will fail, or, if someone else claims the name first, install something else
-> entirely. Until the release workflow runs, install from a clone.
-
 ```bash
-# From a clone of https://github.com/mbeacom/context-kit
-pip install ./plugins/memory      # or: uv tool install ./plugins/memory
+pip install memorykit             # or: uv tool install memorykit
 ```
 
-Once published, that becomes:
+To work from a clone instead — for contributing, or to run an unreleased
+revision:
 
 ```bash
-pip install memorykit             # or: uv tool install memorykit
+# From a clone of https://github.com/mbeacom/context-kit
+pip install ./plugins/memory      # or: uv tool install ./plugins/memory
 ```
 
 Either way that is the whole install: no bootstrap step, no plugin runtime, no
@@ -87,7 +83,8 @@ is the reverse of the `indexkit` launcher's preference, and deliberate.
 
 ## Local-only reviewed records
 
-Python 3 is the only requirement. Configure an explicit project and plugin root:
+Python 3 and Git on `PATH` are required. Configure an explicit project and
+plugin root:
 
 ```bash
 export CONTEXT_KIT_MEMORY_PROJECT=owner/repository
@@ -180,12 +177,13 @@ authoring a `memory-v1` record from a candidate stays an explicit judgment step.
 
 See [`references/session-mining.md`](skills/memory-workflows/references/session-mining.md).
 
-## MCP surface for non-plugin hosts
+## MCP surface
 
 An optional stdio MCP server exposes `memory_recall`, `memory_capture`, and
-`memory_review` so hosts that consume skills plus MCP can use durable memory
-without a plugin runtime. It is standard library only and shells out to the
-same provider, so the CLI and MCP paths cannot drift.
+`memory_review` so hosts that consume skills plus MCP can use durable memory.
+GitHub Copilot and Claude Code plugin installs discover it automatically;
+package-only hosts can launch it directly. It is standard library only and
+shells out to the same provider, so the CLI and MCP paths cannot drift.
 
 ```bash
 # From the plugin:
@@ -196,6 +194,14 @@ CONTEXT_KIT_MEMORY_PROJECT=owner/repository \
 CONTEXT_KIT_MEMORY_PROJECT=owner/repository memorykit-mcp
 ```
 
+The bundled `.mcp.json` forwards `CONTEXT_KIT_MEMORY_PROJECT` from the host
+environment into the plugin process. Set it to the current
+`owner/repository` in the Copilot project environment or before launching the
+host; do not edit Copilot's generated MCP entry. MCP capture records must use
+an absolute `source` path because plugin hosts may launch the server outside
+the active repository. The server refuses an unset project and never infers a
+repository or falls back to a global store.
+
 The surface can propose memory but **cannot activate it**: a record whose
 frontmatter is not `review: proposed` is refused, and proposals stay out of
 active recall until promoted with the append-only `record-state` CLI.
@@ -227,7 +233,7 @@ explicit command there.
 | `/review-memory` | Review freshness, conflicts, and consolidation proposals. |
 | `/archive-handoff` | Explicitly preserve a validated handoff as historical memory. |
 | `memory-provider.py` | Launcher for the `memorykit` provider: stdlib validator, local store, MemPalace adapter, and hook dispatcher. |
-| `src/memorykit/` | The packaged engine (`memorykit`, not yet on PyPI): contract, validator, provider, MCP server. |
+| `src/memorykit/` | The packaged `memorykit` engine: contract, validator, provider, MCP server. |
 
 ## Safety boundaries
 

{memorykit-0.6.0 → memorykit-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memorykit"
-version = "0.6.0"
+version = "0.7.0"
 description = "Provenance-bound durable memory: an immutable record contract, a validator, append-only review state, and a standard-library stdio MCP server. No Python dependencies; requires git on PATH."
 requires-python = ">=3.10"
 keywords = [

{memorykit-0.6.0 → memorykit-0.7.0}/src/memorykit/__init__.py

@@ -19,6 +19,6 @@ Two entry points, one implementation:
 
 from __future__ import annotations
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = ["__version__"]

{memorykit-0.6.0 → memorykit-0.7.0}/src/memorykit/mcp.py

@@ -26,7 +26,7 @@ from pathlib import Path
 from typing import Any
 
 SERVER_NAME = "context-kit-memory"
-SERVER_VERSION = "0.3.0"
+SERVER_VERSION = "0.7.0"
 # Newest first. The client's requested version is echoed when supported.
 SUPPORTED_PROTOCOLS = ("2025-06-18", "2025-03-26", "2024-11-05")
 # The provider is this package's sibling module, so one path is correct in both
@@ -38,6 +38,11 @@ SUPPORTED_PROTOCOLS = ("2025-06-18", "2025-03-26", "2024-11-05")
 PROVIDER = Path(__file__).resolve().with_name("provider.py")
 CALL_TIMEOUT_SECONDS = 120.0
 MAX_RECORD_BYTES = 32 * 1024
+MAX_FRAME_CHARS = MAX_RECORD_BYTES * 8
+EVIDENCE_ERROR_MARKERS = (
+    "referenced source is not a readable file",
+    "source_hash does not match the referenced source file",
+)
 
 PARSE_ERROR = -32700
 INVALID_REQUEST = -32600
@@ -70,14 +75,15 @@ TOOLS: list[dict[str, Any]] = [
             "required": ["query"],
             "additionalProperties": False,
         },
+        "annotations": {"readOnlyHint": True, "openWorldHint": False},
     },
     {
         "name": "memory_capture",
         "description": (
             "Persist a context-kit/memory-v1 record as review: proposed. The "
-            "record must cite real evidence: its source_hash is verified "
-            "against the source file. Proposed records are inert until a human "
-            "accepts them with the record-state CLI."
+            "record must cite real evidence at an absolute source path: its "
+            "source_hash is verified against the source file. Proposed records "
+            "are inert until a human accepts them with the record-state CLI."
         ),
         "inputSchema": {
             "type": "object",
@@ -94,6 +100,12 @@ TOOLS: list[dict[str, Any]] = [
             "required": ["record"],
             "additionalProperties": False,
         },
+        "annotations": {
+            "readOnlyHint": False,
+            "destructiveHint": False,
+            "idempotentHint": True,
+            "openWorldHint": False,
+        },
     },
     {
         "name": "memory_review",
@@ -106,6 +118,7 @@ TOOLS: list[dict[str, Any]] = [
             "properties": {},
             "additionalProperties": False,
         },
+        "annotations": {"readOnlyHint": True, "openWorldHint": False},
     },
 ]
 
@@ -119,26 +132,10 @@ def _log(message: str) -> None:
     print(f"{SERVER_NAME}: {message}", file=sys.stderr, flush=True)
 
 
-def _project_scope() -> str:
-    for name in ("CONTEXT_KIT_MEMORY_PROJECT", "CLAUDE_PLUGIN_OPTION_PROJECT"):
-        # Portable first, then the Claude userConfig fallback the CLI accepts.
-        # Checking only the portable name would make every tool refuse on a
-        # normal Claude install configured through the plugin's option.
-        project = os.environ.get(name, "").strip()
-        if project:
-            return project
-    raise ToolError(
-        "no memory project is configured; set CONTEXT_KIT_MEMORY_PROJECT to "
-        "an explicit owner/repository. Memory is never read from or written "
-        "to an inferred global store."
-    )
-
-
-def _run_provider(argv: list[str]) -> str:
+def _run_provider(argv: list[str], *, redact_evidence_errors: bool = False) -> str:
     if not PROVIDER.is_file():
         raise ToolError(f"memory provider script is missing: {PROVIDER}")
-    project = _project_scope()
-    command = [sys.executable, str(PROVIDER), *argv, "--project", project]
+    command = [sys.executable, str(PROVIDER), *argv]
     try:
         result = subprocess.run(
             command,
@@ -154,23 +151,14 @@ def _run_provider(argv: list[str]) -> str:
         raise ToolError(f"memory command could not run: {exc}") from exc
     if result.returncode != 0:
         detail = result.stderr.decode("utf-8", errors="replace").strip()
+        if redact_evidence_errors and any(
+            marker in detail for marker in EVIDENCE_ERROR_MARKERS
+        ):
+            detail = "memory capture refused: cited source evidence did not validate"
         raise ToolError(detail or f"memory command exited {result.returncode}")
     return result.stdout.decode("utf-8", errors="replace").strip()
 
 
-def _frontmatter_value(record: str, field: str) -> str | None:
-    lines = record.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return None
-    for line in lines[1:]:
-        if line.strip() == "---":
-            break
-        key, separator, value = line.partition(":")
-        if separator and key.strip() == field:
-            return value.strip()
-    return None
-
-
 def _tool_memory_recall(arguments: dict[str, Any]) -> str:
     query = arguments.get("query")
     if not isinstance(query, str) or not query.strip():
@@ -192,38 +180,21 @@ def _tool_memory_capture(arguments: dict[str, Any]) -> str:
         raise ToolError(
             f"record exceeds {MAX_RECORD_BYTES} bytes; keep a memory atomic"
         )
-    review = _frontmatter_value(record, "review")
-    if review is None:
-        raise ToolError("record is missing flat YAML frontmatter with a `review` field")
-    if review != "proposed":
-        # `capture` takes the initial state from frontmatter, so without this
-        # guard an agent could write `review: accepted` and activate a memory
-        # with no human review at all.
-        raise ToolError(
-            "this surface can only propose memory, but the record declares "
-            f"review: {review}. Set `review: proposed` and promote it later "
-            "with `memory-provider.py record-state <id> --review accepted "
-            "--reason ...` after the evidence has been checked."
-        )
-    # `validate_memory` verifies `source_hash` only when the source is a
-    # *regular file* (`source.is_file()`), so `exists()` here would be a weaker
-    # gate than the one it exists to mirror: a record citing a directory would
-    # pass this check, skip hash verification entirely, and persist with any
-    # 64-character hash and unverifiable provenance. Match the provider.
-    source = _frontmatter_value(record, "source")
-    if not source:
-        raise ToolError("record is missing a `source` field citing its evidence")
-    if not Path(source).expanduser().is_file():
-        raise ToolError(
-            f"the cited source is not a readable file: {source}. A memory must "
-            "point at evidence that can be re-read and hashed."
-        )
     handle, temporary = tempfile.mkstemp(prefix="memory-capture-", suffix=".md")
     path = Path(temporary)
     try:
         with os.fdopen(handle, "wb") as stream:
             stream.write(raw)
-        return _run_provider(["capture", str(path)])
+        return _run_provider(
+            [
+                "capture",
+                str(path),
+                "--require-review",
+                "proposed",
+                "--require-absolute-source",
+            ],
+            redact_evidence_errors=True,
+        )
     finally:
         path.unlink(missing_ok=True)
 
@@ -326,7 +297,22 @@ def _write(sink: Any, payload: dict[str, Any]) -> None:
 def serve(stdin: Any = None, stdout: Any = None) -> int:
     source = stdin if stdin is not None else sys.stdin
     sink = stdout if stdout is not None else sys.stdout
-    for line in source:
+    while True:
+        line = source.readline(MAX_FRAME_CHARS + 1)
+        if not line:
+            break
+        if len(line) > MAX_FRAME_CHARS:
+            while line and not line.endswith("\n"):
+                line = source.readline(MAX_FRAME_CHARS + 1)
+            _write(
+                sink,
+                _error(
+                    None,
+                    INVALID_REQUEST,
+                    f"JSON-RPC frame exceeds {MAX_FRAME_CHARS} characters",
+                ),
+            )
+            continue
         line = line.strip()
         if not line:
             continue

{memorykit-0.6.0 → memorykit-0.7.0}/src/memorykit/provider.py

@@ -442,6 +442,7 @@ def _config(args: argparse.Namespace) -> Config:
         getattr(args, "provider", None)
         or _first_env(
             "CONTEXT_KIT_MEMORY_PROVIDER",
+            "PRODUCTIVITY_SKILLS_MEMORY_PROVIDER",
             "CLAUDE_PLUGIN_OPTION_PROVIDER",
         )
         or "none"
@@ -453,6 +454,7 @@ def _config(args: argparse.Namespace) -> Config:
         getattr(args, "home", None)
         or _first_env(
             "CONTEXT_KIT_MEMORY_HOME",
+            "PRODUCTIVITY_SKILLS_MEMORY_HOME",
             "CLAUDE_PLUGIN_OPTION_MEMORY_HOME",
         )
         or "~/.local/share/context-kit/memory"
@@ -460,14 +462,17 @@ def _config(args: argparse.Namespace) -> Config:
     home = Path(home_value).expanduser().resolve()
     project = getattr(args, "project", None) or _first_env(
         "CONTEXT_KIT_MEMORY_PROJECT",
+        "PRODUCTIVITY_SKILLS_MEMORY_PROJECT",
         "CLAUDE_PLUGIN_OPTION_PROJECT",
     )
     auto_value = _first_env(
         "CONTEXT_KIT_MEMORY_AUTO_CAPTURE",
+        "PRODUCTIVITY_SKILLS_MEMORY_AUTO_CAPTURE",
         "CLAUDE_PLUGIN_OPTION_AUTO_CAPTURE",
     )
     recall_value = _first_env(
         "CONTEXT_KIT_MEMORY_RECALL_ON_START",
+        "PRODUCTIVITY_SKILLS_MEMORY_RECALL_ON_START",
         "CLAUDE_PLUGIN_OPTION_RECALL_ON_START",
     )
     return Config(
@@ -611,7 +616,13 @@ def _read_bounded(
     return raw, text
 
 
-def validate_memory(path: Path, *, verify_source: bool = True) -> dict[str, object]:
+def validate_memory(
+    path: Path,
+    *,
+    verify_source: bool = True,
+    require_review: str | None = None,
+    require_absolute_source: bool = False,
+) -> dict[str, object]:
     raw, text = _read_bounded(path)
     fields, body = _parse_frontmatter(text)
     missing = [field for field in REQUIRED_FIELDS if field not in fields]
@@ -633,6 +644,11 @@ def validate_memory(path: Path, *, verify_source: bool = True) -> dict[str, obje
         raise Refusal(f"freshness must be one of {sorted(FRESHNESS_STATES)}")
     if fields["review"] not in REVIEW_STATES:
         raise Refusal(f"review must be one of {sorted(REVIEW_STATES)}")
+    if require_review is not None and fields["review"] != require_review:
+        raise Refusal(
+            f"memory review must be {require_review!r} for this operation; "
+            f"got {fields['review']!r}"
+        )
     if not HASH_RE.fullmatch(fields["source_hash"]):
         raise Refusal("source_hash must be a lowercase SHA-256 digest")
     _validate_timestamp(fields["observed_at"], "observed_at")
@@ -666,8 +682,18 @@ def validate_memory(path: Path, *, verify_source: bool = True) -> dict[str, obje
     _nonempty_section(sections["## Review Notes"], "Review Notes")
 
     source = Path(fields["source"]).expanduser()
-    if verify_source and source.is_file():
-        actual = hashlib.sha256(source.read_bytes()).hexdigest()
+    if require_absolute_source and not source.is_absolute():
+        raise Refusal("memory source must be an absolute path for this operation")
+    if verify_source:
+        if not source.is_file():
+            raise Refusal(f"referenced source is not a readable file: {source}")
+        try:
+            source_bytes = source.read_bytes()
+        except OSError as exc:
+            raise Refusal(
+                f"referenced source is not a readable file: {source}"
+            ) from exc
+        actual = hashlib.sha256(source_bytes).hexdigest()
         if actual != fields["source_hash"]:
             raise Refusal("source_hash does not match the referenced source file")
     return {
@@ -1407,7 +1433,11 @@ def _provider_version(config: Config) -> tuple[str, str]:
 
 def _capture_memory(args: argparse.Namespace, config: Config) -> int:
     source = Path(args.artifact).expanduser().resolve()
-    metadata = validate_memory(source)
+    metadata = validate_memory(
+        source,
+        require_review=args.require_review,
+        require_absolute_source=args.require_absolute_source,
+    )
     _assert_project_matches(metadata, config)
     raw = source.read_bytes()
     destination = config.records_path / f"{metadata['id']}.md"
@@ -2761,6 +2791,8 @@ def _parser() -> argparse.ArgumentParser:
     capture = sub.add_parser("capture")
     capture.add_argument("artifact")
     capture.add_argument("--local-only", action="store_true")
+    capture.add_argument("--require-review", choices=sorted(REVIEW_STATES))
+    capture.add_argument("--require-absolute-source", action="store_true")
     _add_config_args(capture)
 
     archive = sub.add_parser("archive-handoff")