stifler-memex-mcp 0.1.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hill Patel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,157 +1,287 @@
1
1
  <div align="center">
2
2
 
3
- # memex-mcp
3
+ # memex
4
4
 
5
- **A developer context continuity system that builds and maintains a temporal knowledge graph of your codebase.**
5
+ ### Persistent memory for your AI coding agents.
6
6
 
7
- [![PyPI](https://img.shields.io/pypi/v/memex-mcp)](https://pypi.org/project/memex-mcp/)
8
- [![npm](https://img.shields.io/npm/v/stifler-memex-mcp)](https://www.npmjs.com/package/stifler-memex-mcp)
9
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
10
- [![Tests](https://img.shields.io/github/actions/workflow/status/STiFLeR7/memex/ci.yml)](https://github.com/STiFLeR7/memex/actions)
7
+ memex builds a temporal knowledge graph of your codebase and serves it to any MCP-compatible agent — so every session starts knowing your architecture, your decisions, and your open problems. No more cold starts. No more context pasting.
11
8
 
12
- ![memex banner](assets/memex.png)
9
+ [![PyPI](https://img.shields.io/pypi/v/memex-mcp?v=0.3.2)](https://pypi.org/project/memex-mcp/)
10
+ [![PyPI downloads](https://img.shields.io/pypi/dm/memex-mcp)](https://pypistats.org/packages/memex-mcp)
11
+ [![npm](https://img.shields.io/npm/v/stifler-memex-mcp?v=0.3.2)](https://www.npmjs.com/package/stifler-memex-mcp)
12
+ [![npm downloads](https://img.shields.io/npm/dm/stifler-memex-mcp)](https://www.npmjs.com/package/stifler-memex-mcp)
13
+ [![Claude Code marketplace](https://img.shields.io/badge/Claude%20Code-marketplace-7c3aed)](https://github.com/STiFLeR7/claude-plugins)
14
+ [![GitHub stars](https://img.shields.io/github/stars/STiFLeR7/memex?style=flat)](https://github.com/STiFLeR7/memex/stargazers)
15
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
16
+ [![Tests](https://img.shields.io/github/actions/workflow/status/STiFLeR7/memex/publish.yml?branch=master&label=tests)](https://github.com/STiFLeR7/memex/actions)
17
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
13
18
 
14
- > *Inspired by Vannevar Bush's 1945 concept of a machine that remembers everything — memex is a developer context continuity system. It watches your repo, builds a temporal knowledge graph of your codebase, and serves it to any AI coding agent via MCP — so every agent session starts knowing your architecture, your recent decisions, and your open problems. Automatically. Without any manual context pasting.*
19
+ ![memex banner](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex.png)
15
20
 
16
21
  </div>
17
22
 
18
23
  ---
19
24
 
20
- ## The problem
25
+ ## Why memex?
26
+
27
+ Every AI agent session starts blind. You re-paste files, re-explain architecture, watch the agent rediscover a refactor you finished last month. **memex fixes that.**
28
+
29
+ It runs quietly in the background, learning your codebase from every commit. When an agent connects, it already knows what's there.
30
+
31
+ ```text
32
+ Without memex With memex
33
+ ───────────── ──────────
34
+ You: "We use Postgres, not MySQL" Agent: I see you're using Postgres
35
+ You: "Auth lives in services/auth" Agent: Editing services/auth/jwt.py...
36
+ You: "We decided on JWT last week" Agent: Continuing the JWT decision
37
+ You: "Don't touch the migrations" Agent: Skipping migrations/ (locked)
38
+ ```
21
39
 
22
- Every time you open a new agent session — Gemini CLI, Claude Code, Codex — the agent starts blind. You find yourself re-explaining architecture decisions, pasting the same core files, and watching the agent rediscover refactors you finished last month. This cycle wastes tokens, adds friction, and prevents AI agents from becoming deep collaborators. memex eliminates this "cold start" problem by providing agents with a persistent, evolving memory of your project's history and rationale.
40
+ ---
23
41
 
24
42
  ## How it works
25
43
 
26
44
  ```text
27
- ┌──────────────────┐ ┌──────────────┐ ┌─────────────┐
28
- │ Your Repository │ ───► │ memex Watcher│ ───► │ Neo4j │
29
- │ (Files + Git) │ │ (Tree-sitter)│ │ (Knowledge │
30
- └──────────────────┘ └──────────────┘ │ Graph) │
31
- └──────┬──────┘
32
- │
33
- ▼
34
- ┌──────────────────┐ ┌──────────────┐ ┌─────────────┐
35
- │ AI Agent │ ◄─── │ MCP Server │ ◄────┤ Graphiti │
36
- │ (Gemini/Claude) │ │ (stdio) │ │ Engine │
37
- └──────────────────┘ └──────────────┘ └─────────────┘
45
+ ┌──────────────────┐ ┌───────────────┐ ┌─────────────┐
46
+ │ Your Repository │ ──► │ memex Watcher │ ──► │ Neo4j │
47
+ │ files + git │ │ tree-sitter │ │ knowledge │
48
+ │ │ │ + Gemini │ │ graph │
49
+ └──────────────────┘ └───────────────┘ └──────┬──────┘
50
+ │
51
+ ┌──────────────────┐ ┌───────────────┐ │
52
+ │ AI Agent │ ◄── │ MCP Server │ ◄──────────┘
53
+ │ Claude · Gemini │ │ stdio / HTTP │
54
+ │ Codex · others │ │ │
55
+ └──────────────────┘ └───────────────┘
38
56
  ```
39
57
 
40
- memex runs a background watcher that uses tree-sitter to extract structured symbols and Gemini Flash to synthesize technical decisions from git commits. This data is woven into a temporal knowledge graph powered by Graphiti and Neo4j, which maintains a high-fidelity record of how your code evolves. Agents connect to this graph via a standard Model Context Protocol (MCP) server, allowing them to query context on demand rather than requiring manual file-pasting.
58
+ 1. **Watcher** uses tree-sitter to extract symbols and Gemini Flash to synthesize architectural decisions from your commits.
59
+ 2. **Graph** stores everything in Neo4j via [Graphiti](https://github.com/getzep/graphiti) — bitemporally, so every fact has a "true from" and "true until."
60
+ 3. **MCP server** exposes 14 tools any agent can call to read context or write back its own observations.
41
61
 
42
- ## Installation
62
+ ---
63
+
64
+ ## Quickstart
65
+
66
+ ### The fastest path — Claude Code marketplace
67
+
68
+ ```text
69
+ /plugin marketplace add STiFLeR7/claude-plugins
70
+ /plugin install memex-mcp@stifler-marketplace
71
+ ```
72
+
73
+ That's it. The plugin wires up the MCP server so every Claude Code session has memex's 14 tools. You still need Neo4j + a Gemini key locally (see below); the plugin only handles the agent-side wiring.
74
+
75
+ ### Manual install
76
+
77
+ > **Prerequisites:** Python 3.11+, [uv](https://github.com/astral-sh/uv), Docker, a Gemini API key.
43
78
 
44
- **via npx (no install required)**
45
79
  ```bash
80
+ # 1. Start Neo4j
81
+ docker compose -f docker/docker-compose.yml up -d
82
+
83
+ # 2. Create .env in your project root
84
+ cat > .env <<EOF
85
+ NEO4J_URI=bolt://localhost:7687
86
+ NEO4J_USER=neo4j
87
+ NEO4J_PASSWORD=memex-local
88
+ GEMINI_API_KEY=your-key-here
89
+ EOF
90
+
91
+ # 3. Initialize and start watching
46
92
  npx stifler-memex-mcp init --repo .
47
93
  npx stifler-memex-mcp watch --repo .
48
- ```
49
94
 
50
- **via pip / uv**
51
- ```bash
52
- uv add memex-mcp
53
- pip install memex-mcp
95
+ # 4. In a new terminal, serve the context
96
+ npx stifler-memex-mcp serve --repo .
54
97
  ```
55
98
 
56
- **from source**
57
- ```bash
58
- git clone https://github.com/STiFLeR7/memex
59
- cd memex
60
- uv sync
61
- ```
99
+ That's it. Your agent now has memory.
62
100
 
63
- ## Quickstart
101
+ **Install options:**
64
102
 
65
- **Prerequisites**: Python 3.11+, [uv](https://github.com/astral-sh/uv), Docker, and a Gemini API Key.
103
+ | via | command |
104
+ |----|---------|
105
+ | Claude Code marketplace | `/plugin marketplace add STiFLeR7/claude-plugins` then `/plugin install memex-mcp@stifler-marketplace` |
106
+ | npx (no install) | `npx stifler-memex-mcp ...` |
107
+ | uv | `uv add memex-mcp` |
108
+ | pip | `pip install memex-mcp` |
109
+ | source | `git clone github.com/STiFLeR7/memex && uv sync` |
66
110
 
67
- ```bash
68
- # 1. Start Neo4j infrastructure
69
- docker-compose -f docker/docker-compose.yml up -d
70
-
71
- # 2. Configure environment
72
- # In your project root, create a .env file:
73
- # NEO4J_URI=bolt://localhost:7687
74
- # NEO4J_USER=neo4j
75
- # NEO4J_PASSWORD=your_password
76
- # GEMINI_API_KEY=your_api_key
77
-
78
- # 3. Initialize and watch your repo
79
- memex init --repo .
80
- memex watch --repo .
81
-
82
- # 4. Serve the MCP context (in a new terminal)
83
- memex serve --repo .
84
- ```
111
+ ---
85
112
 
86
- ## Connecting your agent
113
+ ## Connect your agent
87
114
 
88
- ### Gemini CLI
89
- Add to `~/.gemini/settings.json`:
115
+ <details>
116
+ <summary><b>Claude Code</b> (one-liner via marketplace)</summary>
117
+
118
+ Easiest — install the plugin and you're done:
119
+
120
+ ```text
121
+ /plugin marketplace add STiFLeR7/claude-plugins
122
+ /plugin install memex-mcp@stifler-marketplace
123
+ ```
124
+
125
+ Or wire it manually in `.claude/settings.json`:
90
126
  ```json
91
127
  {
92
128
  "mcpServers": {
93
129
  "memex": {
130
+ "type": "stdio",
94
131
  "command": "npx",
95
132
  "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
96
133
  }
97
134
  }
98
135
  }
99
136
  ```
137
+ </details>
138
+
139
+ <details>
140
+ <summary><b>Gemini CLI</b></summary>
100
141
 
101
- ### Claude Code
102
- Add to `.claude/settings.json`:
142
+ Add to `~/.gemini/settings.json`:
103
143
  ```json
104
144
  {
105
145
  "mcpServers": {
106
146
  "memex": {
107
- "type": "stdio",
108
147
  "command": "npx",
109
148
  "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
110
149
  }
111
150
  }
112
151
  }
113
152
  ```
153
+ </details>
154
+
155
+ <details>
156
+ <summary><b>Codex</b></summary>
114
157
 
115
- ### Codex
116
158
  Add to `~/.codex/config.toml`:
117
159
  ```toml
118
160
  [mcp_servers.memex]
119
161
  command = "npx"
120
162
  args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
121
163
  ```
164
+ </details>
165
+
166
+ <details>
167
+ <summary><b>Claude's built-in memory tool</b> (v0.3.0+)</summary>
122
168
 
123
- ## MCP tools
124
-
125
- ### Read Tools (Context Retrieval)
126
- | Tool | When to call it | Returns |
127
- |------|-----------------|---------|
128
- | `get_project_context` | At session start to get a project overview. | Markdown briefing of modules, decisions, and debt. |
129
- | `get_symbol_context` | Before editing a specific function or class. | Signatures, callers, callees, and linked history. |
130
- | `get_recent_decisions` | To understand recent architectural shifts. | Chronological list of tech decisions and rationales. |
131
- | `get_open_problems` | To find technical debt or active bugs. | List of problems sorted by severity (Critical → Low). |
132
- | `search_context` | For broad discovery across all node types. | Hybrid search results (semantic + keyword + graph). |
133
- | `get_stale_context` | To identify potentially outdated documentation. | Report of edges with low confidence scores. |
134
-
135
- ### Write Tools (Graph Compounding)
136
- | Tool | When to call it | Returns |
137
- |------|-----------------|---------|
138
- | `record_decision` | After making a technical or architectural choice. | Confirmation with the new Decision ID. |
139
- | `record_problem` | When discovering a bug or technical debt item. | Confirmation with the new Problem ID. |
140
- | `resolve_problem` | When a tracked problem has been fixed. | Confirmation of closure and session link. |
141
- | `invalidate_edge` | When identifying a stale or incorrect fact. | Confirmation of edge invalidation. |
169
+ memex can back Anthropic's native `memory_20250818` tool — Claude reads from a per-session graph projection plus a writable scratch zone.
170
+
171
+ ```bash
172
+ memex memory-tool serve --repo . # in-process (Python)
173
+ memex memory-tool serve --repo . --transport http # FastAPI on :7464
174
+ ```
175
+
176
+ ```python
177
+ from memex.memory_tool import MemexAsyncMemoryTool
178
+ memory_tool = MemexAsyncMemoryTool(repo_root=".")
179
+ client.beta.messages.run_tools(..., tools=[memory_tool])
180
+ ```
181
+
182
+ Run alongside the MCP server for full coverage.
183
+ </details>
184
+
185
+ ---
186
+
187
+ ## What agents can do with memex
188
+
189
+ memex exposes **14 MCP tools** — eight for reading context, four for writing observations back, and two for analysis.
190
+
191
+ ### Reading context
192
+
193
+ | Tool | When |
194
+ |------|------|
195
+ | `get_project_context` | At session start — get the lay of the land |
196
+ | `get_symbol_context` | Before editing a function or class |
197
+ | `get_recent_decisions` | To see what's changed architecturally |
198
+ | `get_open_problems` | To find active bugs and tech debt |
199
+ | `search_context` | Hybrid search across the whole graph |
200
+ | `get_stale_context` | Spot outdated documentation |
201
+ | `explain_change` 🆕 | After a commit — *why* did this happen? |
202
+ | `predict_impact` 🆕 | Before a refactor — *what* might break? |
203
+
204
+ ### Writing observations
205
+
206
+ | Tool | When |
207
+ |------|------|
208
+ | `record_decision` | After making a technical choice |
209
+ | `record_problem` | When you discover a bug or piece of debt |
210
+ | `resolve_problem` | When a tracked problem is fixed |
211
+ | `invalidate_edge` | When a fact is no longer true |
212
+
213
+ Agents write back into the graph as they work. Next session, that knowledge is there.
214
+
215
+ ---
216
+
217
+ ## Highlights
218
+
219
+ - **🧠 Bitemporal memory.** Every fact has a creation time and an optional invalidation time. The graph never forgets — but it knows what's still current.
220
+ - **📉 Two-regime confidence decay.** Validated facts decay slowly; unvalidated ones cross the staleness threshold at exactly 30 days. Old hallucinations lose their grip naturally.
221
+ - **🤝 Human-in-the-loop.** `memex review` opens a TUI to validate machine-synthesized decisions, lowest-confidence first.
222
+ - **🔒 Write governance.** Per-node-type ACL, intent-confirmation on agent writes, and explicit `corroborates` / `supersedes` semantics — no silent duplicates.
223
+ - **🔍 Composite retrieval.** Hybrid search × recency × confidence × rehearsal, with the score breakdown surfaced so agents see *why* a result ranked where it did.
224
+ - **🌐 Multi-repo aware.** Single watcher and MCP server can manage hundreds of repos with zero-config switching.
225
+ - **🖥️ Visual graph.** `memex graph --output graph.html` produces a self-contained D3 force layout with cluster overlays.
226
+ - **🧩 Hierarchical clusters** *(v0.3.1)*. `memex cluster` runs Leiden over a hybrid edge graph (directory co-location + module imports + symbol calls) and groups your codebase into named clusters. `get_project_context()` now returns a cluster-level briefing by default — stays under 1500 tokens whether your repo has 50 modules or 5000. Cluster IDs pin across re-runs via Jaccard ≥ 0.5 so renames are stable; `.memex/clusters.yaml` lets you override any assignment.
227
+
228
+ ---
142
229
 
143
230
  ## How the graph works
144
231
 
145
- The memex knowledge graph is built on a bitemporal model, meaning every relationship has both a creation time and an optional invalidation time. This allows the system to store a complete history of the codebase, enabling agents to query what was true at any point in time. To ensure the context remains relevant, a nightly decay scheduler reduces the confidence of information that hasn't been recently verified or interacted with. This "forgetting" mechanism prevents old documentation from cluttering agent context while still preserving it in the historical graph. Because the system is bidirectional, agent observations compound over time; if an agent records a decision in one session, every subsequent agent session automatically starts with that knowledge.
232
+ The knowledge graph is **bitemporal**: every relationship knows when it was created and when (if ever) it became invalid. Agents can ask *what was true on day X* and get a real answer.
233
+
234
+ Confidence isn't a stored number that mutates — it's **computed at query time** from a node's `base_confidence`, validation status, and time since last reinforcement. Two regimes:
235
+
236
+ - **Validated** (a human said "yes, this is real"): half-life ~139 days.
237
+ - **Unvalidated** (the watcher synthesized it from a commit): crosses the staleness threshold (0.3) at **exactly 30 days**.
238
+
239
+ When an agent records a decision in one session, the next session — yours or someone else's — starts with that knowledge. The graph compounds.
240
+
241
+ ---
242
+
243
+ ## Project structure
244
+
245
+ ```
246
+ memex/
247
+ ├── memex/
248
+ │ ├── extractor/ # tree-sitter + lockfile parsers
249
+ │ ├── graph/ # Neo4j writes, confidence, archive
250
+ │ ├── synthesizer/ # Gemini Flash → Decision nodes
251
+ │ ├── mcp_server/ # 14 MCP tools (read + write + analytic)
252
+ │ ├── memory_tool/ # Anthropic memory_20250818 adapter
253
+ │ ├── watcher/ # daemon + git hooks
254
+ │ └── cli.py # init / watch / serve / review / graph / cluster
255
+ ├── tests/ # 332 tests, ~93% coverage
256
+ ├── docker/ # Neo4j compose
257
+ └── npm/ # npx wrapper
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Contributors
263
+
264
+ <table>
265
+ <tr>
266
+ <td align="center">
267
+ <a href="https://github.com/STiFLeR7"><b>Hill Patel</b></a><br/>
268
+ <sub>Architect &amp; Project Lead</sub>
269
+ </td>
270
+ <td align="center">
271
+ <a href="https://github.com/Nirvaan05"><b>Nirvaan Lagishetty</b></a><br/>
272
+ <sub>Lead Contributor</sub>
273
+ </td>
274
+ </tr>
275
+ </table>
276
+
277
+ Want to contribute? Open an issue or a PR. The codebase is well-tested and welcoming — `uv sync` and `uv run pytest tests/` is all the setup you need.
278
+
279
+ ---
146
280
 
147
- ## Releasing
281
+ ## License & inspiration
148
282
 
149
- 1. Add `PYPI_API_TOKEN` to GitHub repo secrets (Settings → Secrets → Actions)
150
- 2. Add `NPM_TOKEN` to GitHub repo secrets
151
- 3. Push a tag `git tag v0.1.2 && git push origin --tags` to trigger both publishes automatically
283
+ MIT — free to use, modify, and ship.
152
284
 
153
- ## Inspiration
154
- Vannevar Bush's 1945 essay "As We May Think" described the memex as a device that stores all of a person's knowledge, cross-referenced and associative. This project is a small step toward that idea, applied to the context an AI agent needs to work effectively inside a codebase.
285
+ > *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."
155
286
 
156
- ## License
157
- MIT - [STiFLeR7](https://github.com/STiFLeR7)
287
+ This is a small step toward that idea, applied to the context an AI agent needs to work effectively inside a codebase.
package/bin/memex-mcp.js CHANGED
@@ -1,4 +1,4 @@
1
- #!/usr/bin/env node
1
+ #!/usr/bin/env node
2
2
 
3
3
  const { execSync, spawn } = require('child_process');
4
4
 
package/package.json CHANGED
@@ -1,24 +1,41 @@
1
1
  {
2
2
  "name": "stifler-memex-mcp",
3
- "version": "0.1.2",
4
- "description": "Developer context continuity system for AI coding agents via MCP. Inspired by Vannevar Bush's 1945 concept of a machine that remembers everything.",
3
+ "version": "0.3.3",
4
+ "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.",
5
5
  "bin": {
6
- "stifler-memex-mcp": "./bin/memex-mcp.js",
7
6
  "memex-mcp": "./bin/memex-mcp.js",
8
7
  "memex": "./bin/memex-mcp.js"
9
8
  },
10
- "scripts": {
11
- "test": "node bin/memex-mcp.js --help"
9
+ "keywords": [
10
+ "mcp",
11
+ "ai-agents",
12
+ "context",
13
+ "knowledge-graph",
14
+ "gemini",
15
+ "claude-code",
16
+ "neo4j",
17
+ "developer-tools"
18
+ ],
19
+ "author": {
20
+ "name": "Hill Patel",
21
+ "email": "hillaniljppatel@gmail.com",
22
+ "url": "https://github.com/STiFLeR7"
12
23
  },
13
- "keywords": ["mcp", "ai-agents", "context", "knowledge-graph", "gemini", "claude-code"],
14
- "author": "Hill Patel <hillaniljppatel@gmail.com>",
15
24
  "license": "MIT",
16
25
  "repository": {
17
26
  "type": "git",
18
27
  "url": "git+https://github.com/STiFLeR7/memex.git"
19
28
  },
20
- "homepage": "https://github.com/STiFLeR7/memex",
29
+ "bugs": {
30
+ "url": "https://github.com/STiFLeR7/memex/issues"
31
+ },
32
+ "homepage": "https://github.com/STiFLeR7/memex#readme",
21
33
  "engines": {
22
34
  "node": ">=18"
23
- }
35
+ },
36
+ "files": [
37
+ "bin/",
38
+ "README.md",
39
+ "LICENSE"
40
+ ]
24
41
  }