stifler-memex-mcp 0.8.0 → 1.0.0

package/README.md

@@ -1,14 +1,23 @@
-# memex — temporal knowledge graph memory for AI coding agents
+# memex: trusted engineering context for agentic software engineering
 
 <!-- mcp-name: io.github.STiFLeR7/memex -->
 
-> Persistent memory and codebase context for AI coding agents, served over MCP. A bitemporal knowledge graph of your repository — modules, symbols, decisions, problems — for Claude Code, Cursor, Codex, Gemini CLI, and any MCP-compatible agent.
+> A protocol-neutral engineering-context layer for AI coding agents. memex
+> builds a bitemporal knowledge graph of your repository (modules, symbols,
+> decisions, problems, evidence, and code evolution) and exposes bounded,
+> provenance-aware context through Hermes MemoryProvider or MCP.
 
-A daemon and MCP server that turns every commit and every file change into structured graph state: modules, symbols, decisions, problems, lockfile facts. Sessions stop starting blind. Agents stop re-discovering the same refactor every time you `/clear`.
+**[memex.stifler.in](https://memex.stifler.in)**
 
-[![PyPI](https://img.shields.io/pypi/v/memex-mcp?v=0.3.3)](https://pypi.org/project/memex-mcp/)
+A daemon and MCP server that turns commits and file changes into structured
+engineering knowledge. Agents can receive relevant repository context before a
+task, with freshness and provenance preserved, without making memex a source of
+personal memory or raw session state.
+
+[![Website](https://img.shields.io/badge/website-memex.stifler.in-2D6AFF)](https://memex.stifler.in)
+[![PyPI](https://img.shields.io/pypi/v/memex-mcp?v=1.0.0)](https://pypi.org/project/memex-mcp/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/memex-mcp)](https://pypistats.org/packages/memex-mcp)
-[![npm](https://img.shields.io/npm/v/stifler-memex-mcp?v=0.3.3)](https://www.npmjs.com/package/stifler-memex-mcp)
+[![npm](https://img.shields.io/npm/v/stifler-memex-mcp?v=1.0.0)](https://www.npmjs.com/package/stifler-memex-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/stifler-memex-mcp)](https://www.npmjs.com/package/stifler-memex-mcp)
 [![Claude Code marketplace](https://img.shields.io/badge/Claude%20Code-marketplace-7c3aed)](https://github.com/STiFLeR7/claude-plugins)
 [![memex MCP server](https://glama.ai/mcp/servers/STiFLeR7/memex/badges/score.svg)](https://glama.ai/mcp/servers/STiFLeR7/memex)
@@ -18,15 +27,37 @@ A daemon and MCP server that turns every commit and every file change into struc
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/STiFLeR7/memex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/STiFLeR7/memex)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-![memex — temporal knowledge graph MCP server for AI coding agents, built on Graphiti and Neo4j](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex.png)
+[![Memex on AI Agents Listing](https://aiagentslisting.com/memex/badge.svg?claim=1af930b83c7adc182c0f2c52cb300afb)](https://aiagentslisting.com/mcp/memex)
+
+## Where memex lives
+
+| | |
+|---|---|
+| Website | [memex.stifler.in](https://memex.stifler.in) |
+| Source | [github.com/STiFLeR7/memex](https://github.com/STiFLeR7/memex) |
+| Python package | [`memex-mcp` on PyPI](https://pypi.org/project/memex-mcp/) |
+| Node package | [`stifler-memex-mcp` on npm](https://www.npmjs.com/package/stifler-memex-mcp) |
+| MCP Registry | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/), listed as `io.github.STiFLeR7/memex` |
+| Claude Code plugin | [STiFLeR7/claude-plugins](https://github.com/STiFLeR7/claude-plugins) |
+| Directories | [Glama](https://glama.ai/mcp/servers/STiFLeR7/memex) · [AI Agents Listing](https://aiagentslisting.com/mcp/memex) |
+
+Evaluation record in [BENCHMARK.md](BENCHMARK.md), release history in
+[CHANGELOG.md](CHANGELOG.md), reporting process in [SECURITY.md](SECURITY.md),
+and how to work on it in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+[![Watch memex v1 in 60 seconds: how memex keeps Claude Code and Codex sessions current as the code changes](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex-v1-video.jpg?v=1.0.0)](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex-v1.mp4)
+
+▶ **[Watch memex v1 in 60 seconds](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex-v1.mp4)**
 
 ```mermaid
 flowchart LR
     A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
     B --> C[Neo4j graph<br/>bitemporal facts]
-    C --> D[MCP server<br/>stdio / HTTP]
-    D --> E[AI agent<br/>Claude · Cursor · Codex · Gemini CLI]
-    E -.->|writes decisions back| C
+    C --> D[memex core<br/>ContextPacket selection]
+    D --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
+    D --> F[MCP fallback<br/>explicit lookup]
+    E --> G[AI coding agent]
+    F --> G
 
     style B fill:#cfe8ff,stroke:#0066cc,color:#000
     style C fill:#fff4cf,stroke:#cc9900,color:#000
@@ -59,6 +90,30 @@ npx stifler-memex-mcp watch --repo .
 npx stifler-memex-mcp serve --repo .
 ```
 
+### Hermes integration
+
+The v0.9 Hermes integration is read-only. Hermes retains personal memory, raw
+session state, and execution state. memex supplies repository engineering
+context through a bounded `ContextPacket`; it does not ingest Hermes
+`state.db`, transcripts, prompts, or tool results.
+
+Add the memex provider to Hermes' profile configuration:
+
+```yaml
+memory:
+  provider: memex
+plugins:
+  memex:
+    repo_path: /absolute/path/to/repository
+    prefetch_timeout_seconds: 7
+    max_items: 8
+    max_chars: 12000
+```
+
+If Hermes is not installed, use the same context selector through the MCP
+`get_engineering_context` tool. Both paths share the protocol-neutral memex
+core and fail open when retrieval is unavailable.
+
 | Channel | Command |
 |---|---|
 | Claude Code marketplace | `/plugin install memex-mcp@stifler-marketplace` |
@@ -85,14 +140,15 @@ initial admin key, and the `down -v` footgun to avoid.
 | Property | Value |
 |---|---|
 | Output | A Neo4j graph populated continuously from your repo |
-| Storage | Neo4j via [Graphiti](https://github.com/getzep/graphiti). Bitemporal — every edge has `created_at` and optional `expired_at` |
-| Survives | `/clear`, terminal crashes, machine restarts, teammate handoffs |
-| Hands off to | Claude Code, Cursor, Codex, Gemini CLI, any MCP client |
+| Storage | Neo4j via [Graphiti](https://github.com/getzep/graphiti). Bitemporal: every edge has `created_at` and optional `expired_at` |
+| Context | Bounded, ranked, provenance-aware `ContextPacket` |
+| Integrations | Hermes MemoryProvider, MCP resources/tools, Claude Code, Cursor, Codex, Gemini CLI |
+| Failure mode | Fail-open; agent execution continues without memex |
 | Granularity | Scales from 50 to 5000+ modules via hierarchical Leiden clusters |
 | Synthesis | Gemini Flash distills commits into `Decision` nodes; Pro for grounded synthesis |
 | Confidence | Computed at query time. Two-regime decay (validated half-life ~139d, unvalidated stale at 30d) |
 | Write governance | Per-node-type ACL, intent-confirmation on agent writes, explicit `corroborates` / `supersedes` semantics |
-| Tests | 333 passing, ~93% coverage |
+| Goal 10 evidence | 8/8 valid paired runs, 0 treatment failures, 0 treatment regressions |
 
 ## The lifecycle
 
@@ -119,7 +175,7 @@ flowchart TD
 
 ## MCP tools
 
-14 tools — eight read, four write, two analytic.
+14 tools: eight read, four write, two analytic.
 
 ### Read
 
@@ -186,7 +242,7 @@ flowchart LR
 | Algorithm | `graspologic.partition.hierarchical_leiden` with fixed seed |
 | Naming | TF-IDF top-3 over module docstrings + symbol names, parent-dir fallback |
 | ID pinning | Jaccard ≥ 0.5 across reruns (cluster names stay stable through renames) |
-| User overrides | `.memex/clusters.yaml` — any assignment can be locked |
+| User overrides | `.memex/clusters.yaml`, where any assignment can be locked |
 | Context budget | `get_project_context` stays under 1500 tokens whether your repo has 50 or 5000 modules |
 
 ## Measure Your Savings
@@ -289,7 +345,7 @@ args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
 <details>
 <summary><b>Anthropic memory tool (memory_20250818)</b></summary>
 
-memex can back Claude's native memory tool — agents read from a per-session graph projection plus a writable scratch zone.
+memex can back Claude's native memory tool: agents read from a per-session graph projection plus a writable scratch zone.
 
 ```bash
 memex memory-tool serve --repo .                     # in-process
@@ -340,7 +396,7 @@ memex/
 │   ├── memory_tool/      Anthropic memory_20250818 adapter
 │   ├── watcher/          daemon + git hooks
 │   └── cli.py            init / watch / serve / review / graph / cluster
-├── tests/                333 passing, ~93% coverage
+├── tests/                unit, integration, and objective evaluation suites
 ├── docker/               Neo4j compose
 ├── npm/                  npx wrapper (publishes as stifler-memex-mcp)
 └── Dockerfile            introspection-only image for MCP directory sandboxes
@@ -369,11 +425,17 @@ Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7))
 
 ## Core Contributors & Maintainers
 
-- Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7)) — architect, maintainer
-- Nirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05)) — lead contributor, maintainer
+- Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7)), architect and maintainer
+- Nirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05)), lead contributor and maintainer
 
 ## Contributing
 
-Open an issue or PR. `uv sync --all-extras && uv run pytest tests/` is all the setup you need to run the suite. Version bumps must update **both** `pyproject.toml` and `npm/package.json` and they must agree.
+Open an issue or PR. `uv sync --all-extras` installs the development toolchain.
+Run `uv run pytest -m "not integration"` for the offline suite and `uv run ruff
+check .` before opening a PR. Version bumps must update `pyproject.toml`,
+`npm/package.json`, `server.json`, and the team Docker image tag together.
+
+The v0.9 release record is in [`CHANGELOG.md`](CHANGELOG.md), with the
+architecture and evaluation evidence under [`docs/architecture/v0.9/`](docs/architecture/v0.9/).
 
 > *Vannevar Bush, 1945:* "Consider a future device for individual use, which is a sort of mechanized private file and library. It needs a name, and to coin one at random, **memex** will do."

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "stifler-memex-mcp",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "mcpName": "io.github.STiFLeR7/memex",
-  "description": "Developer context continuity system — temporal knowledge graph for AI coding agents via MCP. Inspired by Vannevar Bush's 1945 concept of a machine that remembers everything.",
+  "description": "Trusted engineering context for agentic software engineering via Hermes MemoryProvider and MCP.",
   "bin": {
     "stifler-memex-mcp": "./bin/memex-mcp.js",
     "memex-mcp": "./bin/memex-mcp.js",