stifler-memex-mcp 0.3.5 → 0.3.7
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/README.md +329 -287
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,287 +1,329 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
memex
|
|
8
|
-
|
|
9
|
-
[](https://pypi.org/project/memex-mcp/)
|
|
8
|
+
[](https://pypistats.org/packages/memex-mcp)
|
|
9
|
+
[](https://www.npmjs.com/package/stifler-memex-mcp)
|
|
10
|
+
[](https://www.npmjs.com/package/stifler-memex-mcp)
|
|
11
|
+
[](https://github.com/STiFLeR7/claude-plugins)
|
|
12
|
+
[](https://github.com/STiFLeR7/memex/stargazers)
|
|
13
|
+
[](https://github.com/STiFLeR7/memex/actions)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
```mermaid
|
|
19
|
+
flowchart LR
|
|
20
|
+
A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
|
|
21
|
+
B --> C[Neo4j graph<br/>bitemporal facts]
|
|
22
|
+
C --> D[MCP server<br/>stdio / HTTP]
|
|
23
|
+
D --> E[AI agent<br/>Claude · Cursor · Codex · Gemini CLI]
|
|
24
|
+
E -.->|writes decisions back| C
|
|
25
|
+
|
|
26
|
+
style B fill:#cfe8ff,stroke:#0066cc,color:#000
|
|
27
|
+
style C fill:#fff4cf,stroke:#cc9900,color:#000
|
|
28
|
+
style E fill:#d4f5d4,stroke:#2d8f2d,color:#000
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
### Via Claude Code marketplace
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
/plugin marketplace add STiFLeR7/claude-plugins
|
|
37
|
+
/plugin install memex-mcp@stifler-marketplace
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Restart your Claude Code session.
|
|
41
|
+
|
|
42
|
+
### Manual
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
docker compose -f docker/docker-compose.yml up -d
|
|
46
|
+
cat > .env <<EOF
|
|
47
|
+
NEO4J_URI=bolt://localhost:7687
|
|
48
|
+
NEO4J_USER=neo4j
|
|
49
|
+
NEO4J_PASSWORD=memex-local
|
|
50
|
+
GEMINI_API_KEY=your-key-here
|
|
51
|
+
EOF
|
|
52
|
+
npx stifler-memex-mcp init --repo .
|
|
53
|
+
npx stifler-memex-mcp watch --repo .
|
|
54
|
+
npx stifler-memex-mcp serve --repo .
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
| Channel | Command |
|
|
58
|
+
|---|---|
|
|
59
|
+
| Claude Code marketplace | `/plugin install memex-mcp@stifler-marketplace` |
|
|
60
|
+
| npx (no install) | `npx stifler-memex-mcp <cmd>` |
|
|
61
|
+
| uv | `uv add memex-mcp` |
|
|
62
|
+
| pip | `pip install memex-mcp` |
|
|
63
|
+
| source | `git clone github.com/STiFLeR7/memex && uv sync` |
|
|
64
|
+
|
|
65
|
+
## At a glance
|
|
66
|
+
|
|
67
|
+
| Property | Value |
|
|
68
|
+
|---|---|
|
|
69
|
+
| Output | A Neo4j graph populated continuously from your repo |
|
|
70
|
+
| Storage | Neo4j via [Graphiti](https://github.com/getzep/graphiti). Bitemporal — every edge has `created_at` and optional `expired_at` |
|
|
71
|
+
| Survives | `/clear`, terminal crashes, machine restarts, teammate handoffs |
|
|
72
|
+
| Hands off to | Claude Code, Cursor, Codex, Gemini CLI, any MCP client |
|
|
73
|
+
| Granularity | Scales from 50 to 5000+ modules via hierarchical Leiden clusters |
|
|
74
|
+
| Synthesis | Gemini Flash distills commits into `Decision` nodes; Pro for grounded synthesis |
|
|
75
|
+
| Confidence | Computed at query time. Two-regime decay (validated half-life ~139d, unvalidated stale at 30d) |
|
|
76
|
+
| Write governance | Per-node-type ACL, intent-confirmation on agent writes, explicit `corroborates` / `supersedes` semantics |
|
|
77
|
+
| Tests | 333 passing, ~93% coverage |
|
|
78
|
+
|
|
79
|
+
## The lifecycle
|
|
80
|
+
|
|
81
|
+
```mermaid
|
|
82
|
+
flowchart TD
|
|
83
|
+
Init[memex init<br/>extract baseline] --> Watch[memex watch<br/>daemon + git hooks]
|
|
84
|
+
Watch -->|commit| Extract[tree-sitter extract<br/>symbols, imports, lockfile]
|
|
85
|
+
Extract --> Synth[Gemini Flash<br/>diff → Decision nodes]
|
|
86
|
+
Synth --> Write[Graphiti add_episode<br/>+ post-hoc bitemporal SET]
|
|
87
|
+
Write --> Decay[Scheduler<br/>nightly confidence decay]
|
|
88
|
+
Decay -->|stale edges| Archive[expired_at = now]
|
|
89
|
+
|
|
90
|
+
Serve[memex serve<br/>MCP stdio/HTTP] -.->|reads| Write
|
|
91
|
+
Agent[AI agent] -->|14 MCP tools| Serve
|
|
92
|
+
Serve -->|record_decision / record_problem| Write
|
|
93
|
+
|
|
94
|
+
Cluster[memex cluster<br/>Leiden over hybrid edges] -.->|every N commits| Write
|
|
95
|
+
|
|
96
|
+
style Init fill:#e8f4ff,color:#000
|
|
97
|
+
style Watch fill:#fff4cf,color:#000
|
|
98
|
+
style Synth fill:#ffe0cc,color:#000
|
|
99
|
+
style Serve fill:#d4f5d4,color:#000
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## MCP tools
|
|
103
|
+
|
|
104
|
+
14 tools — eight read, four write, two analytic.
|
|
105
|
+
|
|
106
|
+
### Read
|
|
107
|
+
|
|
108
|
+
| Tool | When |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `get_project_context` | Session start. Returns a cluster-level briefing under 1500 tokens regardless of repo size |
|
|
111
|
+
| `get_symbol_context` | Before editing a function or class. Returns callers, callees, linked decisions |
|
|
112
|
+
| `get_recent_decisions` | Last N days of architectural decisions, optionally module-scoped |
|
|
113
|
+
| `get_open_problems` | Active bugs and tech debt, sorted by severity |
|
|
114
|
+
| `search_context` | Hybrid search: semantic × keyword × graph traversal × RRF merge |
|
|
115
|
+
| `get_stale_context` | Edges whose composite confidence dropped below threshold |
|
|
116
|
+
| `explain_change` | Given a commit SHA, cross-references the diff with linked Decision/Problem nodes and asks Gemini Pro for a grounded explanation |
|
|
117
|
+
| `predict_impact` | Given a file path, returns a ranked list of modules likely affected based on graph coupling (no LLM call) |
|
|
118
|
+
|
|
119
|
+
### Write
|
|
120
|
+
|
|
121
|
+
| Tool | When |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `record_decision` | After making a technical choice. Supports `corroborates` (reinforce) and `supersedes` (replace) |
|
|
124
|
+
| `record_problem` | When discovering a bug or piece of tech debt |
|
|
125
|
+
| `resolve_problem` | When a tracked problem is fixed |
|
|
126
|
+
| `invalidate_edge` | When a stored fact is no longer true |
|
|
127
|
+
|
|
128
|
+
## Bitemporal confidence
|
|
129
|
+
|
|
130
|
+
Confidence is **not** a stored number that mutates. It is computed at query time from `base_confidence`, validation status, time since last reinforcement, and access count.
|
|
131
|
+
|
|
132
|
+
```mermaid
|
|
133
|
+
flowchart LR
|
|
134
|
+
Edge[Edge created<br/>base_confidence] --> Q{Validated by<br/>a human?}
|
|
135
|
+
Q -->|yes| Slow[Slow regime<br/>half-life ~139d]
|
|
136
|
+
Q -->|no| Fast[Fast regime<br/>stale at exactly 30d]
|
|
137
|
+
Slow --> Score[Composite score<br/>conf × recency × rehearsal]
|
|
138
|
+
Fast --> Score
|
|
139
|
+
Score -->|below floor| Stale[get_stale_context surfaces it]
|
|
140
|
+
Score -->|access| Bump[last_reinforced_at updated]
|
|
141
|
+
Bump --> Score
|
|
142
|
+
|
|
143
|
+
style Slow fill:#d4f5d4,color:#000
|
|
144
|
+
style Fast fill:#ffd4d4,color:#000
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
| Property | Value |
|
|
148
|
+
|---|---|
|
|
149
|
+
| Validated half-life | ~139 days |
|
|
150
|
+
| Unvalidated stale threshold | 30 days (composite < 0.3) |
|
|
151
|
+
| Recency τ | 90 days (exponential decay) |
|
|
152
|
+
| Composite formula | `conf × recency × (1 + rehearsal_w × log(1 + access_count))` |
|
|
153
|
+
| Conflict similarity threshold | 0.4 (below this + overlapping validity = conflict) |
|
|
154
|
+
| Intent-confirmation threshold | 0.85 (MCP write similarity check) |
|
|
155
|
+
|
|
156
|
+
## Hierarchical clusters
|
|
157
|
+
|
|
158
|
+
`memex cluster` runs hierarchical Leiden over a hybrid edge graph:
|
|
159
|
+
|
|
160
|
+
| Edge type | Weight |
|
|
161
|
+
|---|---|
|
|
162
|
+
| Directory co-location | 1.0 |
|
|
163
|
+
| Module imports | 2.0 |
|
|
164
|
+
| Symbol calls | `log(1 + calls)` |
|
|
165
|
+
|
|
166
|
+
| Property | Value |
|
|
167
|
+
|---|---|
|
|
168
|
+
| Algorithm | `graspologic.partition.hierarchical_leiden` with fixed seed |
|
|
169
|
+
| Naming | TF-IDF top-3 over module docstrings + symbol names, parent-dir fallback |
|
|
170
|
+
| ID pinning | Jaccard ≥ 0.5 across reruns (cluster names stay stable through renames) |
|
|
171
|
+
| User overrides | `.memex/clusters.yaml` — any assignment can be locked |
|
|
172
|
+
| Context budget | `get_project_context` stays under 1500 tokens whether your repo has 50 or 5000 modules |
|
|
173
|
+
|
|
174
|
+
## Connect your agent
|
|
175
|
+
|
|
176
|
+
<details>
|
|
177
|
+
<summary><b>Claude Code</b></summary>
|
|
178
|
+
|
|
179
|
+
Marketplace install above does this for you. Manual wiring in `.claude/settings.json`:
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"mcpServers": {
|
|
184
|
+
"memex": {
|
|
185
|
+
"type": "stdio",
|
|
186
|
+
"command": "npx",
|
|
187
|
+
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
</details>
|
|
193
|
+
|
|
194
|
+
<details>
|
|
195
|
+
<summary><b>Cursor</b></summary>
|
|
196
|
+
|
|
197
|
+
Add to `~/.cursor/mcp.json`:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"mcpServers": {
|
|
202
|
+
"memex": {
|
|
203
|
+
"command": "npx",
|
|
204
|
+
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
</details>
|
|
210
|
+
|
|
211
|
+
<details>
|
|
212
|
+
<summary><b>Gemini CLI</b></summary>
|
|
213
|
+
|
|
214
|
+
Add to `~/.gemini/settings.json`:
|
|
215
|
+
|
|
216
|
+
```json
|
|
217
|
+
{
|
|
218
|
+
"mcpServers": {
|
|
219
|
+
"memex": {
|
|
220
|
+
"command": "npx",
|
|
221
|
+
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
</details>
|
|
227
|
+
|
|
228
|
+
<details>
|
|
229
|
+
<summary><b>Codex</b></summary>
|
|
230
|
+
|
|
231
|
+
Add to `~/.codex/config.toml`:
|
|
232
|
+
|
|
233
|
+
```toml
|
|
234
|
+
[mcp_servers.memex]
|
|
235
|
+
command = "npx"
|
|
236
|
+
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
237
|
+
```
|
|
238
|
+
</details>
|
|
239
|
+
|
|
240
|
+
<details>
|
|
241
|
+
<summary><b>Anthropic memory tool (memory_20250818)</b></summary>
|
|
242
|
+
|
|
243
|
+
memex can back Claude's native memory tool — agents read from a per-session graph projection plus a writable scratch zone.
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
memex memory-tool serve --repo . # in-process
|
|
247
|
+
memex memory-tool serve --repo . --transport http # FastAPI on :7464
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
from memex.memory_tool import MemexAsyncMemoryTool
|
|
252
|
+
memory_tool = MemexAsyncMemoryTool(repo_root=".")
|
|
253
|
+
client.beta.messages.run_tools(..., tools=[memory_tool])
|
|
254
|
+
```
|
|
255
|
+
</details>
|
|
256
|
+
|
|
257
|
+
## Operating principles
|
|
258
|
+
|
|
259
|
+
| # | Principle | The bet |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| 1 | Bitemporal, never destructive | Edges are expired, not deleted. `WHERE r.expired_at IS NULL` filters live state |
|
|
262
|
+
| 2 | Confidence is computed, not stored | Mutating a number invites silent drift. Recompute every read |
|
|
263
|
+
| 3 | Two regimes for decay | Validated facts decay slowly; unvalidated facts must earn their place by being accessed |
|
|
264
|
+
| 4 | Human in the loop | `memex review` queues lowest-confidence Decision nodes for explicit validation |
|
|
265
|
+
| 5 | Write governance | Per-node-type ACL. `Decision.policy = open`, `Module.policy = locked`. Intent-confirmation on similar-content writes |
|
|
266
|
+
| 6 | Tokens are budgeted | `get_project_context` stays under 1500 tokens at any repo size via Leiden clusters |
|
|
267
|
+
| 7 | Synthesis only on commits | The watcher batches by debounce window. Gemini Flash is not in the hot path of a tool call |
|
|
268
|
+
| 8 | Pro for synthesis, Flash for extraction | `explain_change` uses Pro because grounding matters. Everything else uses Flash |
|
|
269
|
+
| 9 | Multi-repo aware | One watcher + one MCP server can manage hundreds of repos. `--repo` switches scope |
|
|
270
|
+
| 10 | Local-first | Neo4j runs in your Docker. Gemini is the only outbound call, and only on commits |
|
|
271
|
+
|
|
272
|
+
## When to use memex
|
|
273
|
+
|
|
274
|
+
| Use it when | Skip it when |
|
|
275
|
+
|---|---|
|
|
276
|
+
| Multi-week or multi-month project | One-shot script, throwaway prototype |
|
|
277
|
+
| You work across multiple agents (Claude, Cursor, Codex) and want shared context | You only ever pair with one agent on one task |
|
|
278
|
+
| Architectural decisions are made over time and need to be remembered | The whole project fits in a single 200k-token context window |
|
|
279
|
+
| You want to query "what did we decide about X" from any session | Your repo is already small enough to paste into the prompt |
|
|
280
|
+
| Multiple developers using AI agents on the same codebase | Solo work where you never `/clear` |
|
|
281
|
+
|
|
282
|
+
## Project structure
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
memex/
|
|
286
|
+
├── memex/
|
|
287
|
+
│ ├── extractor/ tree-sitter + lockfile parsers
|
|
288
|
+
│ ├── graph/ Neo4j writes, confidence, archive, cluster engine
|
|
289
|
+
│ ├── synthesizer/ Gemini Flash → Decision nodes
|
|
290
|
+
│ ├── mcp_server/ 14 MCP tools (read + write + analytic)
|
|
291
|
+
│ ├── memory_tool/ Anthropic memory_20250818 adapter
|
|
292
|
+
│ ├── watcher/ daemon + git hooks
|
|
293
|
+
│ └── cli.py init / watch / serve / review / graph / cluster
|
|
294
|
+
├── tests/ 333 passing, ~93% coverage
|
|
295
|
+
├── docker/ Neo4j compose
|
|
296
|
+
├── npm/ npx wrapper (publishes as stifler-memex-mcp)
|
|
297
|
+
└── Dockerfile introspection-only image for MCP directory sandboxes
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## Commands
|
|
301
|
+
|
|
302
|
+
| Command | What it does |
|
|
303
|
+
|---|---|
|
|
304
|
+
| `memex init` | Extract baseline graph state, run first cluster pass |
|
|
305
|
+
| `memex watch` | Daemon that listens for file + git events and writes to Neo4j |
|
|
306
|
+
| `memex serve` | Run the MCP server (stdio, HTTP, or both) |
|
|
307
|
+
| `memex review` | TUI that walks lowest-confidence decisions for human validation |
|
|
308
|
+
| `memex graph --output graph.html` | Self-contained D3 force layout with cluster overlays |
|
|
309
|
+
| `memex cluster [--rerun] [--dry-run]` | Run Leiden over the hybrid edge graph; pin cluster IDs by Jaccard ≥ 0.5 |
|
|
310
|
+
| `memex memory-tool serve` | Back Anthropic's `memory_20250818` tool with a graph projection |
|
|
311
|
+
|
|
312
|
+
## License
|
|
313
|
+
|
|
314
|
+
MIT. See [LICENSE](./LICENSE).
|
|
315
|
+
|
|
316
|
+
## Author
|
|
317
|
+
|
|
318
|
+
Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7))
|
|
319
|
+
|
|
320
|
+
## Core Contributors & Maintainers
|
|
321
|
+
|
|
322
|
+
- Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7)) — architect, maintainer
|
|
323
|
+
- Nirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05)) — lead contributor, maintainer
|
|
324
|
+
|
|
325
|
+
## Contributing
|
|
326
|
+
|
|
327
|
+
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.
|
|
328
|
+
|
|
329
|
+
> *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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stifler-memex-mcp",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.7",
|
|
4
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
6
|
"stifler-memex-mcp": "./bin/memex-mcp.js",
|