stifler-memex-mcp 0.1.2 → 0.3.2
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 +21 -0
- package/README.md +195 -88
- package/bin/memex-mcp.js +1 -1
- package/package.json +26 -9
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,264 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
# memex
|
|
3
|
+
# memex
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### Persistent memory for your AI coding agents.
|
|
6
|
+
|
|
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.
|
|
6
8
|
|
|
7
9
|
[](https://pypi.org/project/memex-mcp/)
|
|
8
|
-
[](https://www.npmjs.com/package/memex-mcp)
|
|
9
11
|
[](LICENSE)
|
|
10
12
|
[](https://github.com/STiFLeR7/memex/actions)
|
|
13
|
+
[](https://www.python.org/downloads/)
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
|
|
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.*
|
|
15
|
+
|
|
15
16
|
|
|
16
17
|
</div>
|
|
17
18
|
|
|
18
19
|
---
|
|
19
20
|
|
|
20
|
-
##
|
|
21
|
+
## Why memex?
|
|
22
|
+
|
|
23
|
+
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.**
|
|
21
24
|
|
|
22
|
-
|
|
25
|
+
It runs quietly in the background, learning your codebase from every commit. When an agent connects, it already knows what's there.
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
Without memex With memex
|
|
29
|
+
───────────── ──────────
|
|
30
|
+
You: "We use Postgres, not MySQL" Agent: I see you're using Postgres
|
|
31
|
+
You: "Auth lives in services/auth" Agent: Editing services/auth/jwt.py...
|
|
32
|
+
You: "We decided on JWT last week" Agent: Continuing the JWT decision
|
|
33
|
+
You: "Don't touch the migrations" Agent: Skipping migrations/ (locked)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
---
|
|
23
37
|
|
|
24
38
|
## How it works
|
|
25
39
|
|
|
26
40
|
```text
|
|
27
|
-
┌──────────────────┐
|
|
28
|
-
│ Your Repository │
|
|
29
|
-
│
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
│
|
|
36
|
-
│
|
|
37
|
-
└──────────────────┘
|
|
41
|
+
┌──────────────────┐ ┌───────────────┐ ┌─────────────┐
|
|
42
|
+
│ Your Repository │ ──► │ memex Watcher │ ──► │ Neo4j │
|
|
43
|
+
│ files + git │ │ tree-sitter │ │ knowledge │
|
|
44
|
+
│ │ │ + Gemini │ │ graph │
|
|
45
|
+
└──────────────────┘ └───────────────┘ └──────┬──────┘
|
|
46
|
+
│
|
|
47
|
+
┌──────────────────┐ ┌───────────────┐ │
|
|
48
|
+
│ AI Agent │ ◄── │ MCP Server │ ◄──────────┘
|
|
49
|
+
│ Claude · Gemini │ │ stdio / HTTP │
|
|
50
|
+
│ Codex · others │ │ │
|
|
51
|
+
└──────────────────┘ └───────────────┘
|
|
38
52
|
```
|
|
39
53
|
|
|
40
|
-
|
|
54
|
+
1. **Watcher** uses tree-sitter to extract symbols and Gemini Flash to synthesize architectural decisions from your commits.
|
|
55
|
+
2. **Graph** stores everything in Neo4j via [Graphiti](https://github.com/getzep/graphiti) — bitemporally, so every fact has a "true from" and "true until."
|
|
56
|
+
3. **MCP server** exposes 14 tools any agent can call to read context or write back its own observations.
|
|
41
57
|
|
|
42
|
-
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Quickstart
|
|
61
|
+
|
|
62
|
+
> **Prerequisites:** Python 3.11+, [uv](https://github.com/astral-sh/uv), Docker, a Gemini API key.
|
|
43
63
|
|
|
44
|
-
**via npx (no install required)**
|
|
45
64
|
```bash
|
|
65
|
+
# 1. Start Neo4j
|
|
66
|
+
docker compose -f docker/docker-compose.yml up -d
|
|
67
|
+
|
|
68
|
+
# 2. Create .env in your project root
|
|
69
|
+
cat > .env <<EOF
|
|
70
|
+
NEO4J_URI=bolt://localhost:7687
|
|
71
|
+
NEO4J_USER=neo4j
|
|
72
|
+
NEO4J_PASSWORD=memex-local
|
|
73
|
+
GEMINI_API_KEY=your-key-here
|
|
74
|
+
EOF
|
|
75
|
+
|
|
76
|
+
# 3. Initialize and start watching
|
|
46
77
|
npx stifler-memex-mcp init --repo .
|
|
47
78
|
npx stifler-memex-mcp watch --repo .
|
|
48
|
-
```
|
|
49
79
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
uv add memex-mcp
|
|
53
|
-
pip install memex-mcp
|
|
80
|
+
# 4. In a new terminal, serve the context
|
|
81
|
+
npx stifler-memex-mcp serve --repo .
|
|
54
82
|
```
|
|
55
83
|
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
git clone https://github.com/STiFLeR7/memex
|
|
59
|
-
cd memex
|
|
60
|
-
uv sync
|
|
61
|
-
```
|
|
84
|
+
That's it. Your agent now has memory.
|
|
62
85
|
|
|
63
|
-
|
|
86
|
+
**Install options:**
|
|
64
87
|
|
|
65
|
-
|
|
88
|
+
| via | command |
|
|
89
|
+
|----|---------|
|
|
90
|
+
| npx (no install) | `npx stifler-memex-mcp ...` |
|
|
91
|
+
| uv | `uv add memex-mcp` |
|
|
92
|
+
| pip | `pip install memex-mcp` |
|
|
93
|
+
| source | `git clone github.com/STiFLeR7/memex && uv sync` |
|
|
66
94
|
|
|
67
|
-
|
|
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
|
-
```
|
|
95
|
+
---
|
|
85
96
|
|
|
86
|
-
##
|
|
97
|
+
## Connect your agent
|
|
87
98
|
|
|
88
|
-
|
|
89
|
-
|
|
99
|
+
<details>
|
|
100
|
+
<summary><b>Claude Code</b></summary>
|
|
101
|
+
|
|
102
|
+
Add to `.claude/settings.json`:
|
|
90
103
|
```json
|
|
91
104
|
{
|
|
92
105
|
"mcpServers": {
|
|
93
106
|
"memex": {
|
|
107
|
+
"type": "stdio",
|
|
94
108
|
"command": "npx",
|
|
95
109
|
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
96
110
|
}
|
|
97
111
|
}
|
|
98
112
|
}
|
|
99
113
|
```
|
|
114
|
+
</details>
|
|
100
115
|
|
|
101
|
-
|
|
102
|
-
|
|
116
|
+
<details>
|
|
117
|
+
<summary><b>Gemini CLI</b></summary>
|
|
118
|
+
|
|
119
|
+
Add to `~/.gemini/settings.json`:
|
|
103
120
|
```json
|
|
104
121
|
{
|
|
105
122
|
"mcpServers": {
|
|
106
123
|
"memex": {
|
|
107
|
-
"type": "stdio",
|
|
108
124
|
"command": "npx",
|
|
109
125
|
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
110
126
|
}
|
|
111
127
|
}
|
|
112
128
|
}
|
|
113
129
|
```
|
|
130
|
+
</details>
|
|
131
|
+
|
|
132
|
+
<details>
|
|
133
|
+
<summary><b>Codex</b></summary>
|
|
114
134
|
|
|
115
|
-
### Codex
|
|
116
135
|
Add to `~/.codex/config.toml`:
|
|
117
136
|
```toml
|
|
118
137
|
[mcp_servers.memex]
|
|
119
138
|
command = "npx"
|
|
120
139
|
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
121
140
|
```
|
|
141
|
+
</details>
|
|
142
|
+
|
|
143
|
+
<details>
|
|
144
|
+
<summary><b>Claude's built-in memory tool</b> (v0.3.0+)</summary>
|
|
122
145
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
146
|
+
memex can back Anthropic's native `memory_20250818` tool — Claude reads from a per-session graph projection plus a writable scratch zone.
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
memex memory-tool serve --repo . # in-process (Python)
|
|
150
|
+
memex memory-tool serve --repo . --transport http # FastAPI on :7464
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
from memex.memory_tool import MemexAsyncMemoryTool
|
|
155
|
+
memory_tool = MemexAsyncMemoryTool(repo_root=".")
|
|
156
|
+
client.beta.messages.run_tools(..., tools=[memory_tool])
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Run alongside the MCP server for full coverage.
|
|
160
|
+
</details>
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## What agents can do with memex
|
|
165
|
+
|
|
166
|
+
memex exposes **14 MCP tools** — eight for reading context, four for writing observations back, and two for analysis.
|
|
167
|
+
|
|
168
|
+
### Reading context
|
|
169
|
+
|
|
170
|
+
| Tool | When |
|
|
171
|
+
|------|------|
|
|
172
|
+
| `get_project_context` | At session start — get the lay of the land |
|
|
173
|
+
| `get_symbol_context` | Before editing a function or class |
|
|
174
|
+
| `get_recent_decisions` | To see what's changed architecturally |
|
|
175
|
+
| `get_open_problems` | To find active bugs and tech debt |
|
|
176
|
+
| `search_context` | Hybrid search across the whole graph |
|
|
177
|
+
| `get_stale_context` | Spot outdated documentation |
|
|
178
|
+
| `explain_change` 🆕 | After a commit — *why* did this happen? |
|
|
179
|
+
| `predict_impact` 🆕 | Before a refactor — *what* might break? |
|
|
180
|
+
|
|
181
|
+
### Writing observations
|
|
182
|
+
|
|
183
|
+
| Tool | When |
|
|
184
|
+
|------|------|
|
|
185
|
+
| `record_decision` | After making a technical choice |
|
|
186
|
+
| `record_problem` | When you discover a bug or piece of debt |
|
|
187
|
+
| `resolve_problem` | When a tracked problem is fixed |
|
|
188
|
+
| `invalidate_edge` | When a fact is no longer true |
|
|
189
|
+
|
|
190
|
+
Agents write back into the graph as they work. Next session, that knowledge is there.
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Highlights
|
|
195
|
+
|
|
196
|
+
- **🧠 Bitemporal memory.** Every fact has a creation time and an optional invalidation time. The graph never forgets — but it knows what's still current.
|
|
197
|
+
- **📉 Two-regime confidence decay.** Validated facts decay slowly; unvalidated ones cross the staleness threshold at exactly 30 days. Old hallucinations lose their grip naturally.
|
|
198
|
+
- **🤝 Human-in-the-loop.** `memex review` opens a TUI to validate machine-synthesized decisions, lowest-confidence first.
|
|
199
|
+
- **🔒 Write governance.** Per-node-type ACL, intent-confirmation on agent writes, and explicit `corroborates` / `supersedes` semantics — no silent duplicates.
|
|
200
|
+
- **🔍 Composite retrieval.** Hybrid search × recency × confidence × rehearsal, with the score breakdown surfaced so agents see *why* a result ranked where it did.
|
|
201
|
+
- **🌐 Multi-repo aware.** Single watcher and MCP server can manage hundreds of repos with zero-config switching.
|
|
202
|
+
- **🖥️ Visual graph.** `memex graph --output graph.html` produces a self-contained D3 force layout with cluster overlays.
|
|
203
|
+
- **🧩 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.
|
|
204
|
+
|
|
205
|
+
---
|
|
142
206
|
|
|
143
207
|
## How the graph works
|
|
144
208
|
|
|
145
|
-
The
|
|
209
|
+
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.
|
|
210
|
+
|
|
211
|
+
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:
|
|
212
|
+
|
|
213
|
+
- **Validated** (a human said "yes, this is real"): half-life ~139 days.
|
|
214
|
+
- **Unvalidated** (the watcher synthesized it from a commit): crosses the staleness threshold (0.3) at **exactly 30 days**.
|
|
215
|
+
|
|
216
|
+
When an agent records a decision in one session, the next session — yours or someone else's — starts with that knowledge. The graph compounds.
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Project structure
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
memex/
|
|
224
|
+
├── memex/
|
|
225
|
+
│ ├── extractor/ # tree-sitter + lockfile parsers
|
|
226
|
+
│ ├── graph/ # Neo4j writes, confidence, archive
|
|
227
|
+
│ ├── synthesizer/ # Gemini Flash → Decision nodes
|
|
228
|
+
│ ├── mcp_server/ # 14 MCP tools (read + write + analytic)
|
|
229
|
+
│ ├── memory_tool/ # Anthropic memory_20250818 adapter
|
|
230
|
+
│ ├── watcher/ # daemon + git hooks
|
|
231
|
+
│ └── cli.py # init / watch / serve / review / graph / cluster
|
|
232
|
+
├── tests/ # 332 tests, ~93% coverage
|
|
233
|
+
├── docker/ # Neo4j compose
|
|
234
|
+
└── npm/ # npx wrapper
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## Contributors
|
|
240
|
+
|
|
241
|
+
<table>
|
|
242
|
+
<tr>
|
|
243
|
+
<td align="center">
|
|
244
|
+
<a href="https://github.com/STiFLeR7"><b>Hill Patel</b></a><br/>
|
|
245
|
+
<sub>Architect & Project Lead</sub>
|
|
246
|
+
</td>
|
|
247
|
+
<td align="center">
|
|
248
|
+
<a href="https://github.com/Nirvaan05"><b>Nirvaan Lagishetty</b></a><br/>
|
|
249
|
+
<sub>Lead Contributor</sub>
|
|
250
|
+
</td>
|
|
251
|
+
</tr>
|
|
252
|
+
</table>
|
|
253
|
+
|
|
254
|
+
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.
|
|
255
|
+
|
|
256
|
+
---
|
|
146
257
|
|
|
147
|
-
##
|
|
258
|
+
## License & inspiration
|
|
148
259
|
|
|
149
|
-
|
|
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
|
|
260
|
+
MIT — free to use, modify, and ship.
|
|
152
261
|
|
|
153
|
-
|
|
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.
|
|
262
|
+
> *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
263
|
|
|
156
|
-
|
|
157
|
-
MIT - [STiFLeR7](https://github.com/STiFLeR7)
|
|
264
|
+
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
package/package.json
CHANGED
|
@@ -1,24 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stifler-memex-mcp",
|
|
3
|
-
"version": "0.
|
|
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.2",
|
|
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
|
-
"
|
|
11
|
-
"
|
|
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
|
-
"
|
|
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
|
}
|