context-keeper-mcp 0.1.0__tar.gz

context_keeper_mcp-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.context/

context_keeper_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# Context Keeper MCP Server
+
+Context Keeper maintains project memory across Claude conversations: architectural decisions, pipeline flows, and constraints that must not be forgotten or violated.
+
+## When to Record
+
+### Record a Decision when:
+- You and the user choose between multiple approaches
+- A technical trade-off is made (e.g., "JSON over SQLite because human-editable")
+- A library, pattern, or architecture is selected
+- The user says "let's go with X" after discussing options
+
+Call `record_decision` with summary, rationale, and alternatives considered. Always include constraints_created if the decision limits future choices.
+
+### Record a Pipeline when:
+- A multi-step workflow is established (build, deploy, data processing)
+- Steps have ordering dependencies (A must happen before B)
+- The user describes "the flow" or "the process"
+
+Call `record_pipeline` with ordered steps. Include constraints like "never skip step 2" or "step 3 requires output from step 1."
+
+### Record a Constraint when:
+- The user says "never do X" or "always do Y"
+- A gotcha or footgun is discovered ("running from source breaks the scheduler")
+- A project convention is established ("all API responses use camelCase")
+- An external requirement exists ("must support Python 3.12+")
+
+Call `record_constraint` with the rule, reason, scope, and hardness. Use hardness=absolute for true invariants, advisory for preferences.
+
+## When to Retrieve
+
+### At conversation start:
+1. Call `get_compaction_report` first. If the report shows discrepancies (missing or modified entries), surface them to the user before doing anything else. Missing entries may need to be re-recorded.
+2. Then call `get_project_summary` to orient yourself on the project's decisions, pipelines, and constraints. This prevents you from suggesting changes that violate established patterns.
+
+### Before making architectural changes:
+Call `get_context` with tags or a query describing what you're about to change. Check for conflicting decisions or constraints before proposing changes.
+
+### When the user asks "why did we...":
+Call `get_context` with relevant tags to find the decision with its rationale.
+
+### Before modifying a pipeline:
+Call `get_context` with the pipeline name or tags to see the current flow and its constraints.
+
+## When NOT to Record
+- Trivial implementation details (variable names, formatting choices)
+- Temporary workarounds that will be removed
+- Information already in the code comments or README
+- One-off debugging steps
+
+## Staleness Management
+Periodically (every few sessions or when the user asks), call `prune_stale` to find entries that haven't been verified recently. Present stale entries to the user and ask: "Is this still accurate?" Then either:
+- Call `update_entry` to refresh verified_at (confirming it's still valid)
+- Call `deprecate_entry` if it's no longer relevant
+
+## Tags Convention
+Use lowercase, hyphen-separated tags. Common categories:
+- Component names: auth, api, database, ui, deployment
+- Cross-cutting: architecture, security, performance, testing
+- Project names: skillmatch, conductor (for cross-project references)

context_keeper_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Armstrong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

context_keeper_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: context-keeper-mcp
+Version: 0.1.0
+Summary: MCP server that maintains project context (decisions, pipelines, constraints) across Claude conversations
+Project-URL: Homepage, https://github.com/jarmstrong158/context-keeper
+Project-URL: Repository, https://github.com/jarmstrong158/context-keeper
+Project-URL: Issues, https://github.com/jarmstrong158/context-keeper/issues
+Author-email: Jonathan Armstrong <jarmstrong158@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,context,decisions,mcp,memory,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.jarmstrong158/context-keeper -->
+
+# Context Keeper
+
+Project memory for Claude. Records design decisions, pipeline flows, and constraints so Claude maintains context across conversations.
+
+## The Problem
+
+As conversations get long, Claude loses the "why" behind earlier decisions. New conversations start blank. This causes Claude to make changes that break established patterns — like rewriting a pipeline step it doesn't remember exists.
+
+## The Solution
+
+Context Keeper gives Claude 8 tools to record and retrieve structured project context:
+
+| Tool | Purpose |
+|------|---------|
+| `record_decision` | Save a decision with rationale and alternatives |
+| `record_pipeline` | Save a multi-step workflow with ordering |
+| `record_constraint` | Save a rule with scope and enforcement level |
+| `get_context` | Retrieve relevant entries by query, tags, scope, or ID |
+| `get_project_summary` | Compact overview for conversation start |
+| `update_entry` | Update any entry by ID |
+| `deprecate_entry` | Retire an entry with reason |
+| `prune_stale` | Find entries not verified recently |
+| `get_compaction_report` | Check if last compaction lost any context |
+
+All data stored as human-editable JSON files in `.context/` inside your project directory. Zero external dependencies.
+
+## Install
+
+```bash
+pip install context-keeper
+```
+
+### Claude Code
+
+```bash
+claude mcp add --scope user context-keeper -- python /path/to/context-keeper/server.py
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context-keeper": {
+      "command": "python",
+      "args": ["/path/to/context-keeper/server.py"],
+      "env": {
+        "CONTEXT_KEEPER_PROJECT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Set `CONTEXT_KEEPER_PROJECT` to the root of your project. If omitted, it uses the current working directory.
+
+## How It Works
+
+### Recording Context
+
+When you make a design decision:
+```
+You: Let's use JSON files instead of SQLite for storage.
+Claude: [calls record_decision with summary, rationale, and alternatives]
+```
+
+When you establish a workflow:
+```
+You: The deploy pipeline is: run tests, build, push to registry, deploy.
+Claude: [calls record_pipeline with ordered steps]
+```
+
+When you set a rule:
+```
+You: Never run Conductor from source. Always use the exe.
+Claude: [calls record_constraint with rule, reason, and hardness=absolute]
+```
+
+### Retrieving Context
+
+At conversation start, Claude calls `get_project_summary` to see all active decisions, pipelines, and constraints. Before making changes, it calls `get_context` with relevant tags to check for conflicts.
+
+### Relevance Scoring
+
+Without embeddings or external services, Context Keeper scores entries using:
+- **Tag match** — overlap between query and entry tags
+- **Text match** — query words found in summary/rationale/rule text
+- **Recency** — recently verified entries score higher
+- **Status** — active entries prioritized over superseded
+
+Results are capped by a configurable token budget (default: 4000 tokens).
+
+## Claude Code Hook Setup
+
+Context Keeper includes hooks that snapshot your context before Claude Code compaction and detect if anything was lost afterward.
+
+Add to your Claude Code hooks config (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python /path/to/context-keeper/hooks/pre_compact.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python /path/to/context-keeper/hooks/post_compact.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/context-keeper` with the actual install path. Set `CONTEXT_KEEPER_PROJECT` env var if your project isn't in the current working directory.
+
+At session start, Claude calls `get_compaction_report` to check if the last compaction lost any context entries. If discrepancies are found, they're surfaced before any work begins.
+
+## Data Storage
+
+```
+your-project/
+  .context/
+    decisions.json           # Design decisions with rationale
+    pipelines.json           # Multi-step workflows
+    constraints.json         # Rules and invariants
+    config.json              # Token budget, stale threshold
+    compaction_snapshot.json  # Pre-compaction snapshot (auto-generated)
+    compaction_report.json   # Post-compaction diff report (auto-generated)
+    hook.log                 # Hook activity log
+```
+
+All files are human-readable JSON. You can edit them directly. IDs are sequential and readable: `dec-001`, `pipe-001`, `con-001`.
+
+## Configuration
+
+Create `.context/config.json` to customize:
+
+```json
+{
+  "project_name": "my-project",
+  "token_budget": 4000,
+  "max_entry_tokens": 1000,
+  "stale_threshold_days": 30
+}
+```
+
+## Cross-Project Context
+
+Query another project's context by passing `project_dir`:
+
+```
+Claude: [calls get_context with project_dir="/path/to/other-project"]
+```
+
+Or tag entries with other project names for cross-referencing.

context_keeper_mcp-0.1.0/README.md

@@ -0,0 +1,173 @@
+<!-- mcp-name: io.github.jarmstrong158/context-keeper -->
+
+# Context Keeper
+
+Project memory for Claude. Records design decisions, pipeline flows, and constraints so Claude maintains context across conversations.
+
+## The Problem
+
+As conversations get long, Claude loses the "why" behind earlier decisions. New conversations start blank. This causes Claude to make changes that break established patterns — like rewriting a pipeline step it doesn't remember exists.
+
+## The Solution
+
+Context Keeper gives Claude 8 tools to record and retrieve structured project context:
+
+| Tool | Purpose |
+|------|---------|
+| `record_decision` | Save a decision with rationale and alternatives |
+| `record_pipeline` | Save a multi-step workflow with ordering |
+| `record_constraint` | Save a rule with scope and enforcement level |
+| `get_context` | Retrieve relevant entries by query, tags, scope, or ID |
+| `get_project_summary` | Compact overview for conversation start |
+| `update_entry` | Update any entry by ID |
+| `deprecate_entry` | Retire an entry with reason |
+| `prune_stale` | Find entries not verified recently |
+| `get_compaction_report` | Check if last compaction lost any context |
+
+All data stored as human-editable JSON files in `.context/` inside your project directory. Zero external dependencies.
+
+## Install
+
+```bash
+pip install context-keeper
+```
+
+### Claude Code
+
+```bash
+claude mcp add --scope user context-keeper -- python /path/to/context-keeper/server.py
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context-keeper": {
+      "command": "python",
+      "args": ["/path/to/context-keeper/server.py"],
+      "env": {
+        "CONTEXT_KEEPER_PROJECT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Set `CONTEXT_KEEPER_PROJECT` to the root of your project. If omitted, it uses the current working directory.
+
+## How It Works
+
+### Recording Context
+
+When you make a design decision:
+```
+You: Let's use JSON files instead of SQLite for storage.
+Claude: [calls record_decision with summary, rationale, and alternatives]
+```
+
+When you establish a workflow:
+```
+You: The deploy pipeline is: run tests, build, push to registry, deploy.
+Claude: [calls record_pipeline with ordered steps]
+```
+
+When you set a rule:
+```
+You: Never run Conductor from source. Always use the exe.
+Claude: [calls record_constraint with rule, reason, and hardness=absolute]
+```
+
+### Retrieving Context
+
+At conversation start, Claude calls `get_project_summary` to see all active decisions, pipelines, and constraints. Before making changes, it calls `get_context` with relevant tags to check for conflicts.
+
+### Relevance Scoring
+
+Without embeddings or external services, Context Keeper scores entries using:
+- **Tag match** — overlap between query and entry tags
+- **Text match** — query words found in summary/rationale/rule text
+- **Recency** — recently verified entries score higher
+- **Status** — active entries prioritized over superseded
+
+Results are capped by a configurable token budget (default: 4000 tokens).
+
+## Claude Code Hook Setup
+
+Context Keeper includes hooks that snapshot your context before Claude Code compaction and detect if anything was lost afterward.
+
+Add to your Claude Code hooks config (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python /path/to/context-keeper/hooks/pre_compact.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python /path/to/context-keeper/hooks/post_compact.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/context-keeper` with the actual install path. Set `CONTEXT_KEEPER_PROJECT` env var if your project isn't in the current working directory.
+
+At session start, Claude calls `get_compaction_report` to check if the last compaction lost any context entries. If discrepancies are found, they're surfaced before any work begins.
+
+## Data Storage
+
+```
+your-project/
+  .context/
+    decisions.json           # Design decisions with rationale
+    pipelines.json           # Multi-step workflows
+    constraints.json         # Rules and invariants
+    config.json              # Token budget, stale threshold
+    compaction_snapshot.json  # Pre-compaction snapshot (auto-generated)
+    compaction_report.json   # Post-compaction diff report (auto-generated)
+    hook.log                 # Hook activity log
+```
+
+All files are human-readable JSON. You can edit them directly. IDs are sequential and readable: `dec-001`, `pipe-001`, `con-001`.
+
+## Configuration
+
+Create `.context/config.json` to customize:
+
+```json
+{
+  "project_name": "my-project",
+  "token_budget": 4000,
+  "max_entry_tokens": 1000,
+  "stale_threshold_days": 30
+}
+```
+
+## Cross-Project Context
+
+Query another project's context by passing `project_dir`:
+
+```
+Claude: [calls get_context with project_dir="/path/to/other-project"]
+```
+
+Or tag entries with other project names for cross-referencing.

context_keeper_mcp-0.1.0/hooks/post_compact.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Context Keeper — PostCompact hook.
+
+Fires after Claude Code compaction (via Stop hook). Compares current context
+state against the pre-compaction snapshot and reports any discrepancies.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+CONTEXT_DIR_NAME = ".context"
+PROJECT_DIR = os.environ.get("CONTEXT_KEEPER_PROJECT", os.getcwd())
+CONTEXT_DIR = os.path.join(PROJECT_DIR, CONTEXT_DIR_NAME)
+SNAPSHOT_PATH = os.path.join(CONTEXT_DIR, "compaction_snapshot.json")
+REPORT_PATH = os.path.join(CONTEXT_DIR, "compaction_report.json")
+LOG_PATH = os.path.join(CONTEXT_DIR, "hook.log")
+
+FILES = {
+    "decisions": os.path.join(CONTEXT_DIR, "decisions.json"),
+    "pipelines": os.path.join(CONTEXT_DIR, "pipelines.json"),
+    "constraints": os.path.join(CONTEXT_DIR, "constraints.json"),
+}
+
+
+def read_json(path):
+    if not os.path.exists(path):
+        return []
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, list) else []
+    except Exception:
+        return []
+
+
+def log(message):
+    try:
+        os.makedirs(CONTEXT_DIR, exist_ok=True)
+        ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+        with open(LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(f"[{ts}] {message}\n")
+    except Exception:
+        pass
+
+
+def diff_entries(before, after):
+    """Compare two entry dicts. Returns dict of changed fields."""
+    changes = {}
+    all_keys = set(before.keys()) | set(after.keys())
+    skip = {"verified_at", "updated_at"}  # timestamps change naturally
+    for key in all_keys:
+        if key in skip:
+            continue
+        bval = before.get(key)
+        aval = after.get(key)
+        if bval != aval:
+            changes[key] = {"before": bval, "after": aval}
+    return changes
+
+
+def main():
+    if not os.path.exists(SNAPSHOT_PATH):
+        return
+
+    try:
+        with open(SNAPSHOT_PATH, "r", encoding="utf-8") as f:
+            snapshot = json.load(f)
+    except Exception:
+        log("POST_COMPACT: Could not read snapshot file")
+        return
+
+    missing = []
+    modified = []
+
+    for type_name, before_entries in snapshot.get("entries", {}).items():
+        path = FILES.get(type_name)
+        if not path:
+            continue
+
+        after_entries = read_json(path)
+        after_by_id = {e.get("id"): e for e in after_entries}
+
+        for before_entry in before_entries:
+            eid = before_entry.get("id")
+            if not eid:
+                continue
+
+            after_entry = after_by_id.get(eid)
+            if after_entry is None:
+                missing.append({
+                    "type": type_name,
+                    "entry": before_entry,
+                })
+            else:
+                changes = diff_entries(before_entry, after_entry)
+                if changes:
+                    modified.append({
+                        "type": type_name,
+                        "id": eid,
+                        "changes": changes,
+                    })
+
+    has_discrepancies = len(missing) > 0 or len(modified) > 0
+    status = "discrepancies_found" if has_discrepancies else "clean"
+
+    report = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "snapshot_timestamp": snapshot.get("timestamp"),
+        "status": status,
+        "missing_entries": missing,
+        "modified_entries": modified,
+        "missing_count": len(missing),
+        "modified_count": len(modified),
+    }
+
+    os.makedirs(CONTEXT_DIR, exist_ok=True)
+    with open(REPORT_PATH, "w", encoding="utf-8") as f:
+        json.dump(report, f, indent=2)
+
+    if has_discrepancies:
+        print(f"[Context Keeper] WARNING: Compaction discrepancies detected!", file=sys.stderr)
+        print(f"  Missing entries: {len(missing)}", file=sys.stderr)
+        print(f"  Modified entries: {len(modified)}", file=sys.stderr)
+        print(f"  Report: {REPORT_PATH}", file=sys.stderr)
+        print(f"  Call get_compaction_report to review details.", file=sys.stderr)
+        log(f"POST_COMPACT: DISCREPANCIES — {len(missing)} missing, {len(modified)} modified")
+    else:
+        log("POST_COMPACT: clean — no discrepancies")
+
+
+if __name__ == "__main__":
+    main()

context_keeper_mcp-0.1.0/hooks/pre_compact.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Context Keeper — PreCompact hook.
+
+Fires before Claude Code compaction. Snapshots all active context entries
+so post_compact.py can detect if anything was lost.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+CONTEXT_DIR_NAME = ".context"
+PROJECT_DIR = os.environ.get("CONTEXT_KEEPER_PROJECT", os.getcwd())
+CONTEXT_DIR = os.path.join(PROJECT_DIR, CONTEXT_DIR_NAME)
+SNAPSHOT_PATH = os.path.join(CONTEXT_DIR, "compaction_snapshot.json")
+LOG_PATH = os.path.join(CONTEXT_DIR, "hook.log")
+
+FILES = {
+    "decisions": os.path.join(CONTEXT_DIR, "decisions.json"),
+    "pipelines": os.path.join(CONTEXT_DIR, "pipelines.json"),
+    "constraints": os.path.join(CONTEXT_DIR, "constraints.json"),
+}
+
+
+def read_json(path):
+    if not os.path.exists(path):
+        return []
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, list) else []
+    except Exception:
+        return []
+
+
+def log(message):
+    try:
+        os.makedirs(CONTEXT_DIR, exist_ok=True)
+        ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+        with open(LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(f"[{ts}] {message}\n")
+    except Exception:
+        pass
+
+
+def main():
+    if not os.path.exists(CONTEXT_DIR):
+        return
+
+    snapshot = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "entries": {},
+        "counts": {},
+    }
+
+    for type_name, path in FILES.items():
+        entries = read_json(path)
+        active = [e for e in entries if e.get("status", "active") != "deprecated"]
+        snapshot["entries"][type_name] = active
+        snapshot["counts"][type_name] = len(active)
+
+    total = sum(snapshot["counts"].values())
+
+    os.makedirs(CONTEXT_DIR, exist_ok=True)
+    with open(SNAPSHOT_PATH, "w", encoding="utf-8") as f:
+        json.dump(snapshot, f, indent=2)
+
+    counts_str = ", ".join(f"{k}={v}" for k, v in snapshot["counts"].items())
+    log(f"PRE_COMPACT: {total} active entries ({counts_str})")
+
+
+if __name__ == "__main__":
+    main()