mneme-cc-plugin 2.0.0__tar.gz

mneme_cc_plugin-2.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "mneme",
+  "version": "2.0.0",
+  "description": "Vault-native memory for Claude Code. Markdown is ground truth. Hybrid retrieval, temporal knowledge graph, zero LLM cost on Stop, token-aware adaptive context.",
+  "author": {
+    "name": "Onour Impram",
+    "url": "https://github.com/TheGoatPsy/mneme"
+  },
+  "homepage": "https://github.com/TheGoatPsy/mneme",
+  "repository": "https://github.com/TheGoatPsy/mneme",
+  "license": "MIT",
+  "keywords": [
+    "memory",
+    "mcp",
+    "vault",
+    "fts5",
+    "retrieval",
+    "temporal"
+  ]
+}

mneme_cc_plugin-2.0.0/.gitignore

@@ -0,0 +1,88 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+*.tsbuildinfo
+
+# TypeScript
+*.js.map
+*.d.ts.map
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# OS
+Thumbs.db
+desktop.ini
+
+# mneme local
+.mneme/
+*.local.json
+vault-test/
+benchmarks/results/
+benchmarks/_runs/
+benchmarks/*/output/
+benchmarks/*/result.json
+benchmarks/*/hardware.json
+
+# Secrets
+.env.local
+.env.*.local
+secrets/
+*.key
+*.pem
+
+# Build artifacts
+*.tgz
+*.whl

mneme_cc_plugin-2.0.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mneme": {
+      "command": "mneme-mcp",
+      "args": []
+    }
+  }
+}

mneme_cc_plugin-2.0.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: mneme-cc-plugin
+Version: 2.0.0
+Summary: Claude Code plugin for mneme: hooks, slash commands, skills, and the install CLI.
+Project-URL: Homepage, https://github.com/TheGoatPsy/mneme
+Project-URL: Repository, https://github.com/TheGoatPsy/mneme
+Project-URL: Issues, https://github.com/TheGoatPsy/mneme/issues
+Author: Onour Impram
+License: MIT
+Keywords: claude-code,fts5,mcp,memory,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: mneme-core<3,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mneme-cc-plugin
+
+Claude Code plugin manifest for [mneme](https://github.com/TheGoatPsy/mneme).
+
+## Hooks
+
+| Hook | Purpose | Latency budget |
+|---|---|---|
+| `PostToolUse` | Capture tool output with `distill.shell_compress` compression and stage for indexing. | non-blocking background |
+| `SessionStart` | Inject preflight vault context with `distill.injection_dedup`. | under 500ms p95 |
+| `Stop` | Append session summary deterministically. No LLM call on the critical path. | under 1s p95 |
+| `PreCompact` | Snapshot pre-compaction state for recovery. | under 200ms p95 |
+| `SessionEnd` | Flush staging buffers, schedule opt-in background compression. | under 500ms p95 |
+
+## Commands
+
+- `/mneme:prime` loads context for the current task.
+- `/mneme:recall` retrieves a specific session.
+- `/mneme:migrate` runs one-command migration from claude-mem.
+
+## Skills
+
+- `mneme-prime` is the context priming workflow.
+- `mneme-search` is the vault search workflow. v1.0 search is FTS5, with RRF and KG surfaces gated as documented in the root README.
+
+## Installation
+
+```bash
+mneme install --profile=lite
+```
+
+This mutates your Claude Code `settings.json` in a BOM-safe way (Windows-friendly), invokes Python via the launcher (`py -3` on Windows), and registers all hooks, commands, the MCP server, and skills.
+
+## Three-Tier Install Profiles
+
+- `lite`: hooks + commands + 6 MCP tools (Python + Node only).
+- `standard`: lite + optional ONNX runtime slot and RRF extension points. Packaged LEANN retrieval is roadmap.
+- `full`: standard + gated Graphiti temporal knowledge graph enrichment for summarize and timeline (Docker + Neo4j required).
+
+Upgrade in place: `mneme upgrade --profile=standard`.
+
+## License
+
+MIT. See LICENSE in the repository root.

mneme_cc_plugin-2.0.0/README.md

@@ -0,0 +1,44 @@
+# mneme-cc-plugin
+
+Claude Code plugin manifest for [mneme](https://github.com/TheGoatPsy/mneme).
+
+## Hooks
+
+| Hook | Purpose | Latency budget |
+|---|---|---|
+| `PostToolUse` | Capture tool output with `distill.shell_compress` compression and stage for indexing. | non-blocking background |
+| `SessionStart` | Inject preflight vault context with `distill.injection_dedup`. | under 500ms p95 |
+| `Stop` | Append session summary deterministically. No LLM call on the critical path. | under 1s p95 |
+| `PreCompact` | Snapshot pre-compaction state for recovery. | under 200ms p95 |
+| `SessionEnd` | Flush staging buffers, schedule opt-in background compression. | under 500ms p95 |
+
+## Commands
+
+- `/mneme:prime` loads context for the current task.
+- `/mneme:recall` retrieves a specific session.
+- `/mneme:migrate` runs one-command migration from claude-mem.
+
+## Skills
+
+- `mneme-prime` is the context priming workflow.
+- `mneme-search` is the vault search workflow. v1.0 search is FTS5, with RRF and KG surfaces gated as documented in the root README.
+
+## Installation
+
+```bash
+mneme install --profile=lite
+```
+
+This mutates your Claude Code `settings.json` in a BOM-safe way (Windows-friendly), invokes Python via the launcher (`py -3` on Windows), and registers all hooks, commands, the MCP server, and skills.
+
+## Three-Tier Install Profiles
+
+- `lite`: hooks + commands + 6 MCP tools (Python + Node only).
+- `standard`: lite + optional ONNX runtime slot and RRF extension points. Packaged LEANN retrieval is roadmap.
+- `full`: standard + gated Graphiti temporal knowledge graph enrichment for summarize and timeline (Docker + Neo4j required).
+
+Upgrade in place: `mneme upgrade --profile=standard`.
+
+## License
+
+MIT. See LICENSE in the repository root.

mneme_cc_plugin-2.0.0/commands/migrate.md

@@ -0,0 +1,41 @@
+# /mneme:migrate
+
+Import existing memory data from another memory plugin into the vault.
+
+## Usage
+
+```
+/mneme:migrate from=claude-mem [path=<custom path>]
+```
+
+## What it does
+
+Invokes `mneme migrate-from-<source>` under the hood. The migration:
+
+1. Reads the source memory store at the default or supplied path.
+2. Maps each record into a markdown document with frontmatter that
+   matches the vault contract.
+3. Writes the converted documents under `vault/migrated/<source>/`.
+4. Rebuilds the FTS5 index incrementally so the imported documents
+   are searchable immediately.
+5. Reports per-record success and any skipped or malformed entries.
+
+The original source store is not modified. If the migration is
+interrupted, re-running is safe: existing destination files are
+detected by content hash and not overwritten.
+
+## Supported sources at v1.0
+
+- `claude-mem` (SQLite observation database).
+
+Future sources (`mem0`, `supermemory`, `episodic-memory`, `letta`,
+`zep`) ship in v1.1 and later.
+
+## Verification
+
+After migration, run `/mneme:search <known fact>` to confirm the
+imported records are indexed. Or use the standalone CLI:
+
+```
+mneme doctor --vault <your-vault>
+```

mneme_cc_plugin-2.0.0/commands/prime.md

@@ -0,0 +1,36 @@
+# /mneme:prime
+
+Inject preflight context for the current task into the conversation.
+
+## Usage
+
+```
+/mneme:prime <task description>
+```
+
+The task description is free text. The longer and more specific, the
+better mneme can match relevant vault content.
+
+## What it does
+
+Calls the `mneme_prime` MCP tool with the supplied task description.
+The tool returns a markdown bundle that contains:
+
+- The most recent session-typed vault documents.
+- Vault documents whose content matches tokens in the task description.
+
+Both selections are formatted with vault paths so you can navigate
+to source content directly. The bundle is truncated to fit within the
+configured token budget (default 4000 tokens).
+
+## When to use
+
+- Starting a new session that picks up a long-running thread.
+- Switching topics mid-session and wanting Claude oriented before
+  the first prompt.
+- Before a code review session where prior decisions matter.
+
+## Related
+
+- `/mneme:recall` to fetch a specific session by id or date.
+- `/mneme:migrate` to bring data over from another memory plugin.

mneme_cc_plugin-2.0.0/commands/recall.md

@@ -0,0 +1,31 @@
+# /mneme:recall
+
+Retrieve a specific past session by id or by date range.
+
+## Usage
+
+```
+/mneme:recall session=<session_id>
+/mneme:recall from=<YYYY-MM-DD> to=<YYYY-MM-DD>
+/mneme:recall                          # most recent sessions
+```
+
+## What it does
+
+Calls the `mneme_recall` MCP tool. The tool reads only the FTS5 index
+and the on-disk markdown files. No LLM call is made. Returns matching
+sessions ranked by mtime descending with full markdown bodies when
+the `include_body` argument is true (default).
+
+## Use cases
+
+- "What did we decide about authentication last Thursday?"
+- "Pull up the session where I sketched the migration plan."
+- "List the last five sessions, no bodies, just titles."
+
+## Tips
+
+- Combine with `/mneme:prime` when you want a curated bundle instead
+  of raw session text.
+- The session_id format follows your vault's frontmatter convention.
+  If you do not know it, prefer `from`/`to` date ranges.

mneme_cc_plugin-2.0.0/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|Bash|Task|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "mneme hook post-tool-use", "timeout": 5 }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "mneme hook session-start", "timeout": 5 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "mneme hook stop", "timeout": 10 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "mneme hook pre-compact", "timeout": 5 }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          { "type": "command", "command": "mneme hook session-end", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}

mneme_cc_plugin-2.0.0/plugin.json

@@ -0,0 +1,56 @@
+{
+  "name": "mneme",
+  "version": "2.0.0",
+  "description": "Vault-native memory for Claude Code. Markdown is ground truth.",
+  "author": "Onour Impram (TheGoatPsy)",
+  "license": "MIT",
+  "repository": "https://github.com/TheGoatPsy/mneme",
+  "documentation": "https://github.com/TheGoatPsy/mneme/blob/main/docs/HOOKS.md",
+  "hooks": {
+    "PostToolUse": {
+      "module": "mneme_cc_plugin.hooks.post_tool_use",
+      "matcher": "Edit|Write|Bash|Task|MultiEdit",
+      "timeout_ms": 1000
+    },
+    "SessionStart": {
+      "module": "mneme_cc_plugin.hooks.session_start",
+      "timeout_ms": 800
+    },
+    "Stop": {
+      "module": "mneme_cc_plugin.hooks.stop",
+      "timeout_ms": 2000
+    },
+    "PreCompact": {
+      "module": "mneme_cc_plugin.hooks.pre_compact",
+      "timeout_ms": 500
+    },
+    "SessionEnd": {
+      "module": "mneme_cc_plugin.hooks.session_end",
+      "timeout_ms": 800
+    }
+  },
+  "commands": {
+    "/mneme:prime": "commands/prime.md",
+    "/mneme:recall": "commands/recall.md",
+    "/mneme:migrate": "commands/migrate.md"
+  },
+  "skills": [
+    "skills/mneme-prime",
+    "skills/mneme-search"
+  ],
+  "mcp_servers": {
+    "mneme": {
+      "command": "mneme-mcp",
+      "args": []
+    }
+  },
+  "engines": {
+    "claude-code": ">=2.0.0",
+    "python": ">=3.11",
+    "node": ">=20"
+  },
+  "kill_switch": {
+    "env": "MNEME_DISABLED",
+    "description": "When this environment variable is truthy, all hooks exit immediately with success."
+  }
+}

mneme_cc_plugin-2.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mneme-cc-plugin"
+version = "2.0.0"
+description = "Claude Code plugin for mneme: hooks, slash commands, skills, and the install CLI."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Onour Impram" }]
+requires-python = ">=3.11"
+keywords = ["claude-code", "mcp", "memory", "vault", "fts5"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "mneme-core>=2.0.0,<3",
+  "click>=8.1,<9",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2",
+  "pytest-cov>=5.0",
+  "ruff>=0.4.7",
+  "mypy>=1.10",
+]
+
+[project.scripts]
+mneme = "mneme_cc_plugin.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/TheGoatPsy/mneme"
+Repository = "https://github.com/TheGoatPsy/mneme"
+Issues = "https://github.com/TheGoatPsy/mneme/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mneme_cc_plugin"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"plugin.json" = "share/mneme-cc-plugin/plugin.json"
+"hooks" = "share/mneme-cc-plugin/hooks"
+"commands" = "share/mneme-cc-plugin/commands"
+"skills" = "share/mneme-cc-plugin/skills"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --cov=mneme_cc_plugin --cov-branch --cov-report=term-missing --cov-fail-under=80"

mneme_cc_plugin-2.0.0/skills/mneme-prime/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: mneme-prime
+description: Use when the user starts a new task that may have prior vault context worth surfacing. Invokes mneme_prime to build a token-budgeted preamble of recent sessions and topic matches.
+---
+
+# mneme-prime
+
+You are guiding the user into a new task. Before answering, retrieve
+relevant prior context from their vault using the `mneme_prime` MCP
+tool.
+
+## When to invoke
+
+- The user starts the conversation with a task description that
+  sounds like it continues prior work.
+- The user explicitly says "remember what we did about X" or
+  similar.
+- The user types `/mneme:prime` directly.
+
+## How to invoke
+
+Call `mneme_prime` with the user's task description as
+`task_description` and a budget no larger than 4000 tokens. Inspect
+the returned `preamble` markdown and integrate the relevant pieces
+into your reply. Cite paths from the `sources` array so the user
+can navigate.
+
+## What not to do
+
+- Do not call `mneme_prime` on every message. The hook system
+  already injects session-start context once per session.
+- Do not include the full preamble verbatim in your reply. Summarize
+  and cite. The preamble is for you, not the user.
+- Do not call this with a `budget_tokens` higher than the user's
+  remaining context window minus a safe reserve. Smaller is better.

mneme_cc_plugin-2.0.0/skills/mneme-search/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: mneme-search
+description: Use when the user asks a factual question whose answer might live in the vault. Invokes mneme_search (FTS5 BM25, optionally fused with dense and KG backends in standard and full profiles).
+---
+
+# mneme-search
+
+When the user asks a question that sounds like recall from prior
+work or notes, search the vault first instead of guessing.
+
+## When to invoke
+
+- "Did we decide X?"
+- "What was the conclusion about Y?"
+- "Show me everything I have on Z."
+- The user types `/mneme:search` directly (when that surface exists).
+
+## How to invoke
+
+Call the `mneme_search` MCP tool with:
+
+- `query`: the user's question in natural language.
+- `top_k`: 5 by default. Raise to 10 only when the user asks for a
+  broad sweep.
+- Optional `filters.date_from` / `filters.date_to` when the user
+  scopes their question to a specific time window.
+
+Inspect the returned `hits`. Each has `path`, `title`, `snippet`,
+and a relevance `score`. Read the snippets first. If they answer
+the question, cite the path and reply. If they only partially
+answer, follow up with `mneme_recall` on the most promising paths
+to pull the full body.
+
+## What not to do
+
+- Do not invoke this for the user's first hello or for questions
+  whose answer is general knowledge.
+- Do not search for the same query twice in a row. If the first
+  pass returned nothing useful, refine the query terms or change
+  the filter window.
+- Do not present raw snippets in your reply unless the user
+  explicitly asks for them. Summarize and link.

mneme_cc_plugin-2.0.0/src/mneme_cc_plugin/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code plugin package for mneme."""
+
+__version__ = "2.0.0"

mneme_cc_plugin-2.0.0/src/mneme_cc_plugin/cli.py

@@ -0,0 +1,12 @@
+"""Top-level entry point for the ``mneme`` console script.
+
+This module exists so ``project.scripts.mneme`` in ``pyproject.toml``
+can stay short. The actual CLI logic lives in
+``mneme_cc_plugin.install.cli``.
+"""
+
+from __future__ import annotations
+
+from mneme_cc_plugin.install.cli import main
+
+__all__ = ["main"]

mneme_cc_plugin-2.0.0/src/mneme_cc_plugin/hooks/__init__.py

@@ -0,0 +1,11 @@
+"""Claude Code hook implementations for the mneme plugin.
+
+Each hook module exposes a ``main()`` entry point that reads a JSON
+event from stdin, performs its task, and writes a JSON response to
+stdout. Every hook fails closed: any exception inside the hook is
+caught and converted to a benign success response so Claude Code is
+never blocked by a mneme defect.
+
+The ``MNEME_DISABLED`` environment variable acts as a global kill
+switch. When truthy, every hook short-circuits before doing any work.
+"""