stifler-memex-mcp 0.1.1 → 0.1.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/README.md +157 -0
- package/bin/memex-mcp.js +12 -27
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# memex-mcp
|
|
4
|
+
|
|
5
|
+
**A developer context continuity system that builds and maintains a temporal knowledge graph of your codebase.**
|
|
6
|
+
|
|
7
|
+
[](https://pypi.org/project/memex-mcp/)
|
|
8
|
+
[](https://www.npmjs.com/package/stifler-memex-mcp)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://github.com/STiFLeR7/memex/actions)
|
|
11
|
+
|
|
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
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## The problem
|
|
21
|
+
|
|
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.
|
|
23
|
+
|
|
24
|
+
## How it works
|
|
25
|
+
|
|
26
|
+
```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
|
+
└──────────────────┘ └──────────────┘ └─────────────┘
|
|
38
|
+
```
|
|
39
|
+
|
|
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.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
**via npx (no install required)**
|
|
45
|
+
```bash
|
|
46
|
+
npx stifler-memex-mcp init --repo .
|
|
47
|
+
npx stifler-memex-mcp watch --repo .
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**via pip / uv**
|
|
51
|
+
```bash
|
|
52
|
+
uv add memex-mcp
|
|
53
|
+
pip install memex-mcp
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**from source**
|
|
57
|
+
```bash
|
|
58
|
+
git clone https://github.com/STiFLeR7/memex
|
|
59
|
+
cd memex
|
|
60
|
+
uv sync
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Quickstart
|
|
64
|
+
|
|
65
|
+
**Prerequisites**: Python 3.11+, [uv](https://github.com/astral-sh/uv), Docker, and a Gemini API Key.
|
|
66
|
+
|
|
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
|
+
```
|
|
85
|
+
|
|
86
|
+
## Connecting your agent
|
|
87
|
+
|
|
88
|
+
### Gemini CLI
|
|
89
|
+
Add to `~/.gemini/settings.json`:
|
|
90
|
+
```json
|
|
91
|
+
{
|
|
92
|
+
"mcpServers": {
|
|
93
|
+
"memex": {
|
|
94
|
+
"command": "npx",
|
|
95
|
+
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Claude Code
|
|
102
|
+
Add to `.claude/settings.json`:
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"mcpServers": {
|
|
106
|
+
"memex": {
|
|
107
|
+
"type": "stdio",
|
|
108
|
+
"command": "npx",
|
|
109
|
+
"args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Codex
|
|
116
|
+
Add to `~/.codex/config.toml`:
|
|
117
|
+
```toml
|
|
118
|
+
[mcp_servers.memex]
|
|
119
|
+
command = "npx"
|
|
120
|
+
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
|
|
121
|
+
```
|
|
122
|
+
|
|
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. |
|
|
142
|
+
|
|
143
|
+
## How the graph works
|
|
144
|
+
|
|
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.
|
|
146
|
+
|
|
147
|
+
## Releasing
|
|
148
|
+
|
|
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
|
|
152
|
+
|
|
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.
|
|
155
|
+
|
|
156
|
+
## License
|
|
157
|
+
MIT - [STiFLeR7](https://github.com/STiFLeR7)
|
package/bin/memex-mcp.js
CHANGED
|
@@ -1,45 +1,30 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
const { execSync, spawn } = require('child_process');
|
|
4
|
-
const path = require('path');
|
|
5
4
|
|
|
6
|
-
function
|
|
5
|
+
function isCommand(cmd) {
|
|
7
6
|
try {
|
|
8
7
|
execSync(`${cmd} --version`, { stdio: 'ignore' });
|
|
9
|
-
} catch {
|
|
10
|
-
console.error(`[stifler-memex-mcp] ${label} is required but not found.`);
|
|
11
|
-
console.error(`[stifler-memex-mcp] Install it from: ${installUrl}`);
|
|
12
|
-
process.exit(1);
|
|
13
|
-
}
|
|
14
|
-
}
|
|
15
|
-
|
|
16
|
-
function hasPythonPackage() {
|
|
17
|
-
try {
|
|
18
|
-
execSync('python -m memex --help', { stdio: 'ignore' });
|
|
19
8
|
return true;
|
|
20
9
|
} catch {
|
|
21
10
|
return false;
|
|
22
11
|
}
|
|
23
12
|
}
|
|
24
13
|
|
|
25
|
-
// Prerequisite
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
if (!hasPythonPackage()) {
|
|
31
|
-
console.log('[stifler-memex-mcp] Installing memex-mcp Python package from PyPI...');
|
|
32
|
-
try {
|
|
33
|
-
execSync('uv pip install memex-mcp', { stdio: 'inherit' });
|
|
34
|
-
} catch {
|
|
35
|
-
console.error('[stifler-memex-mcp] Failed to install memex-mcp. Run: uv pip install memex-mcp');
|
|
36
|
-
process.exit(1);
|
|
37
|
-
}
|
|
14
|
+
// Prerequisite check: uv is required for the most reliable experience
|
|
15
|
+
if (!isCommand('uv')) {
|
|
16
|
+
console.error('[stifler-memex-mcp] uv is required but not found.');
|
|
17
|
+
console.error('[stifler-memex-mcp] Install it from: https://docs.astral.sh/uv/getting-started/installation/');
|
|
18
|
+
process.exit(1);
|
|
38
19
|
}
|
|
39
20
|
|
|
40
|
-
// Delegate all args to the Python memex CLI
|
|
21
|
+
// Delegate all args to the Python memex CLI via 'uv tool run'
|
|
22
|
+
// This ensures that the package is installed in an isolated environment with all dependencies.
|
|
41
23
|
const args = process.argv.slice(2);
|
|
42
|
-
|
|
24
|
+
|
|
25
|
+
// We use '--from memex-mcp' because the package name is memex-mcp on PyPI,
|
|
26
|
+
// but it provides the 'memex' executable.
|
|
27
|
+
const child = spawn('uv', ['tool', 'run', '--from', 'memex-mcp', 'memex', ...args], {
|
|
43
28
|
stdio: 'inherit',
|
|
44
29
|
shell: process.platform === 'win32',
|
|
45
30
|
});
|
package/package.json
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stifler-memex-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
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.",
|
|
5
5
|
"bin": {
|
|
6
|
+
"stifler-memex-mcp": "./bin/memex-mcp.js",
|
|
6
7
|
"memex-mcp": "./bin/memex-mcp.js",
|
|
7
8
|
"memex": "./bin/memex-mcp.js"
|
|
8
9
|
},
|
|
@@ -14,7 +15,7 @@
|
|
|
14
15
|
"license": "MIT",
|
|
15
16
|
"repository": {
|
|
16
17
|
"type": "git",
|
|
17
|
-
"url": "https://github.com/STiFLeR7/memex"
|
|
18
|
+
"url": "git+https://github.com/STiFLeR7/memex.git"
|
|
18
19
|
},
|
|
19
20
|
"homepage": "https://github.com/STiFLeR7/memex",
|
|
20
21
|
"engines": {
|