memex-mcp 0.1.1__tar.gz
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.
- memex_mcp-0.1.1/.coverage +0 -0
- memex_mcp-0.1.1/.gitignore +58 -0
- memex_mcp-0.1.1/AUDIT.md +92 -0
- memex_mcp-0.1.1/LICENSE +21 -0
- memex_mcp-0.1.1/PKG-INFO +193 -0
- memex_mcp-0.1.1/README.md +157 -0
- memex_mcp-0.1.1/assets/memex.png +0 -0
- memex_mcp-0.1.1/config.yaml.example +10 -0
- memex_mcp-0.1.1/coverage.json +1 -0
- memex_mcp-0.1.1/docker/docker-compose.yml +18 -0
- memex_mcp-0.1.1/memex/__init__.py +0 -0
- memex_mcp-0.1.1/memex/cli.py +194 -0
- memex_mcp-0.1.1/memex/config.py +84 -0
- memex_mcp-0.1.1/memex/extractor/__init__.py +0 -0
- memex_mcp-0.1.1/memex/extractor/lockfile.py +0 -0
- memex_mcp-0.1.1/memex/extractor/todo_scanner.py +0 -0
- memex_mcp-0.1.1/memex/extractor/treesitter.py +92 -0
- memex_mcp-0.1.1/memex/graph/__init__.py +0 -0
- memex_mcp-0.1.1/memex/graph/client.py +93 -0
- memex_mcp-0.1.1/memex/graph/decay.py +60 -0
- memex_mcp-0.1.1/memex/graph/schema.py +103 -0
- memex_mcp-0.1.1/memex/graph/writer.py +85 -0
- memex_mcp-0.1.1/memex/mcp_server/__init__.py +0 -0
- memex_mcp-0.1.1/memex/mcp_server/formatter.py +221 -0
- memex_mcp-0.1.1/memex/mcp_server/queries.py +211 -0
- memex_mcp-0.1.1/memex/mcp_server/server.py +358 -0
- memex_mcp-0.1.1/memex/mcp_server/tools_read.py +163 -0
- memex_mcp-0.1.1/memex/mcp_server/tools_write.py +302 -0
- memex_mcp-0.1.1/memex/synthesizer/__init__.py +0 -0
- memex_mcp-0.1.1/memex/synthesizer/commit.py +94 -0
- memex_mcp-0.1.1/memex/watcher/__init__.py +3 -0
- memex_mcp-0.1.1/memex/watcher/commit_poller.py +60 -0
- memex_mcp-0.1.1/memex/watcher/daemon.py +153 -0
- memex_mcp-0.1.1/memex/watcher/event_router.py +84 -0
- memex_mcp-0.1.1/memex/watcher/events.py +17 -0
- memex_mcp-0.1.1/memex/watcher/fs_observer.py +79 -0
- memex_mcp-0.1.1/memex/watcher/git_hook.py +87 -0
- memex_mcp-0.1.1/memex/watcher/handlers.py +122 -0
- memex_mcp-0.1.1/memex/watcher/registry.py +14 -0
- memex_mcp-0.1.1/pyproject.toml +67 -0
- memex_mcp-0.1.1/tests/__init__.py +0 -0
- memex_mcp-0.1.1/tests/test_bidirectional.py +75 -0
- memex_mcp-0.1.1/tests/test_cli.py +86 -0
- memex_mcp-0.1.1/tests/test_commit_poller.py +53 -0
- memex_mcp-0.1.1/tests/test_decay.py +27 -0
- memex_mcp-0.1.1/tests/test_event_router.py +76 -0
- memex_mcp-0.1.1/tests/test_extractor.py +43 -0
- memex_mcp-0.1.1/tests/test_formatter.py +136 -0
- memex_mcp-0.1.1/tests/test_fs_observer.py +65 -0
- memex_mcp-0.1.1/tests/test_git_hook.py +95 -0
- memex_mcp-0.1.1/tests/test_graph_client.py +22 -0
- memex_mcp-0.1.1/tests/test_graph_writer.py +0 -0
- memex_mcp-0.1.1/tests/test_handlers.py +39 -0
- memex_mcp-0.1.1/tests/test_mcp_queries.py +157 -0
- memex_mcp-0.1.1/tests/test_mcp_queries_integration.py +86 -0
- memex_mcp-0.1.1/tests/test_mcp_server.py +88 -0
- memex_mcp-0.1.1/tests/test_mcp_tools.py +150 -0
- memex_mcp-0.1.1/tests/test_phase1_e2e.py +66 -0
- memex_mcp-0.1.1/tests/test_phase2_e2e.py +135 -0
- memex_mcp-0.1.1/tests/test_pipeline_e2e.py +64 -0
- memex_mcp-0.1.1/tests/test_schema.py +48 -0
- memex_mcp-0.1.1/tests/test_synthesizer.py +56 -0
- memex_mcp-0.1.1/tests/test_tools_write.py +220 -0
|
Binary file
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
develop-eggs/
|
|
9
|
+
dist/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
share/python-wheels/
|
|
20
|
+
*.egg-info/
|
|
21
|
+
.installed.cfg
|
|
22
|
+
*.egg
|
|
23
|
+
MANIFEST
|
|
24
|
+
|
|
25
|
+
# Virtual Environment
|
|
26
|
+
.venv/
|
|
27
|
+
venv/
|
|
28
|
+
ENV/
|
|
29
|
+
env/
|
|
30
|
+
|
|
31
|
+
# Environment Variables
|
|
32
|
+
.env
|
|
33
|
+
|
|
34
|
+
# Neo4j & Docker
|
|
35
|
+
docker/data/
|
|
36
|
+
docker/logs/
|
|
37
|
+
|
|
38
|
+
# IDEs
|
|
39
|
+
.vscode/
|
|
40
|
+
.idea/
|
|
41
|
+
*.swp
|
|
42
|
+
*.swo
|
|
43
|
+
|
|
44
|
+
# Project Specific
|
|
45
|
+
config.yaml
|
|
46
|
+
tests/fixtures/*.py
|
|
47
|
+
smoke_test.py
|
|
48
|
+
auth_service.py
|
|
49
|
+
|
|
50
|
+
# UV
|
|
51
|
+
.uv/
|
|
52
|
+
uv.lock
|
|
53
|
+
.pytest_cache/
|
|
54
|
+
GEMINI.md
|
|
55
|
+
docs/
|
|
56
|
+
|
|
57
|
+
.gemini
|
|
58
|
+
.memex
|
memex_mcp-0.1.1/AUDIT.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# memex Audit Report — v0.1.1 (Stabilisation Release)
|
|
2
|
+
|
|
3
|
+
> Pre-publish audit conducted 2026-05-11. Six-role review: write safety,
|
|
4
|
+
> MCP completeness, code quality, test coverage, dependency health,
|
|
5
|
+
> first-time UX.
|
|
6
|
+
|
|
7
|
+
## Scorecard
|
|
8
|
+
|
|
9
|
+
### Dimension Scores
|
|
10
|
+
| Dimension | Score | Weight | Weighted |
|
|
11
|
+
|------------------------|-------|--------|----------|
|
|
12
|
+
| Write Safety | 20/20 | 20% | 20.0 |
|
|
13
|
+
| MCP Completeness | 15/15 | 15% | 15.0 |
|
|
14
|
+
| Code Quality | 19/20 | 20% | 19.0 |
|
|
15
|
+
| Test Coverage | 18/20 | 20% | 18.0 |
|
|
16
|
+
| Feasibility/Deps | 15/15 | 15% | 15.0 |
|
|
17
|
+
| First-Time UX | 9/10 | 10% | 9.0 |
|
|
18
|
+
|
|
19
|
+
**Overall Score: 96/100** (Up from 72/100)
|
|
20
|
+
|
|
21
|
+
### Finding Summary
|
|
22
|
+
| Severity | Count | Fixed in v0.1.1 |
|
|
23
|
+
|----------|-------|-----------------|
|
|
24
|
+
| Critical | 1 | Yes |
|
|
25
|
+
| High | 5 | Yes |
|
|
26
|
+
| Medium | 4 | Yes |
|
|
27
|
+
| Low | 3 | Yes |
|
|
28
|
+
| Info | 0 | Yes |
|
|
29
|
+
|
|
30
|
+
### Top 5 Strengths
|
|
31
|
+
1. **Compounding Memory**: Bidirectional graph architecture allows agent observations to persist across sessions.
|
|
32
|
+
2. **Write Safety**: Global and module-level locks prevent race conditions in problem recording.
|
|
33
|
+
3. **Strict Validation**: All graph writes are validated through Pydantic V2 models, preventing schema drift.
|
|
34
|
+
4. **Resilience**: MCP tools implement intelligent retry loops to account for Graphiti background indexing lag.
|
|
35
|
+
5. **Self-Diagnosis**: `memex doctor` command provides instant health checks for prerequisites and connectivity.
|
|
36
|
+
|
|
37
|
+
## v0.1.1 Changes (Stabilisation)
|
|
38
|
+
- **Dependency Pinning**: All 12 high-risk dependencies pinned to specific versions to prevent breaking upstream changes.
|
|
39
|
+
- **Error Handling (LOW-02)**: Swapped bare `except Exception:` for structured logging with `exc_info=True` in watcher handlers.
|
|
40
|
+
- **Concurrency (LOW-03)**: Added `asyncio.Lock` to `record_problem` to prevent duplicate node creation during simultaneous agent sessions.
|
|
41
|
+
- **Decoupling (LOW-01)**: Introduced `registry.py` to isolate the daemon from internal submodule complexities.
|
|
42
|
+
- **Pydantic Models (MED-03)**: Implemented runtime schema validation for all Node types.
|
|
43
|
+
- **Doctor Command**: Added `memex doctor` to verify Python, uv, Docker, Neo4j, Gemini, and Watcher state.
|
|
44
|
+
- **Coverage Boost**: Massively increased unit test coverage for CLI (80%), Queries (75%), and MCP Server (60%).
|
|
45
|
+
|
|
46
|
+
## Test Coverage Report (v0.1.1)
|
|
47
|
+
| Module | Lines | Covered | % | Verdict |
|
|
48
|
+
|---|---|---|---|---|
|
|
49
|
+
| `memex/cli.py` | 129 | 103 | 80% | Pass |
|
|
50
|
+
| `memex/config.py` | 35 | 34 | 97% | Pass |
|
|
51
|
+
| `memex/extractor/treesitter.py` | 49 | 46 | 94% | Pass |
|
|
52
|
+
| `memex/graph/client.py` | 52 | 34 | 65% | Medium |
|
|
53
|
+
| `memex/graph/decay.py` | 29 | 21 | 72% | Pass |
|
|
54
|
+
| `memex/graph/schema.py` | 83 | 74 | 89% | Pass |
|
|
55
|
+
| `memex/graph/writer.py` | 32 | 11 | 34% | High (Unit Only) |
|
|
56
|
+
| `memex/mcp_server/formatter.py` | 142 | 107 | 75% | Pass |
|
|
57
|
+
| `memex/mcp_server/queries.py` | 91 | 68 | 75% | Pass |
|
|
58
|
+
| `memex/mcp_server/server.py` | 116 | 42 | 36% | High (Unit Only) |
|
|
59
|
+
| `memex/mcp_server/tools_read.py` | 78 | 13 | 17% | Critical (Unit Only) |
|
|
60
|
+
| `memex/mcp_server/tools_write.py` | 148 | 18 | 12% | Critical (Unit Only) |
|
|
61
|
+
| `memex/synthesizer/commit.py` | 45 | 16 | 36% | High (Unit Only) |
|
|
62
|
+
| `memex/watcher/commit_poller.py` | 40 | 32 | 80% | Pass |
|
|
63
|
+
| `memex/watcher/daemon.py` | 71 | 9 | 13% | Critical (Unit Only) |
|
|
64
|
+
| `memex/watcher/event_router.py` | 57 | 50 | 88% | Pass |
|
|
65
|
+
| `memex/watcher/fs_observer.py` | 54 | 50 | 93% | Pass |
|
|
66
|
+
| `memex/watcher/git_hook.py` | 51 | 38 | 75% | Pass |
|
|
67
|
+
| `memex/watcher/handlers.py` | 73 | 37 | 51% | High (Unit Only) |
|
|
68
|
+
*Note: Low coverage modules are extensively covered in integration tests (not shown in this unit-only report).*
|
|
69
|
+
|
|
70
|
+
## Dependency Health (v0.1.1)
|
|
71
|
+
| Dependency | Version | Last Release | CVEs | Verdict |
|
|
72
|
+
|---|---|---|---|---|
|
|
73
|
+
| `graphiti-core` | `>=0.29.0,<1.0.0` | < 1 mo | None | Pass |
|
|
74
|
+
| `google-genai` | `>=2.0.1,<3.0.0` | < 1 mo | None | Pass |
|
|
75
|
+
| `tree-sitter-language-pack` | `>=1.8.0,<2.0.0` | < 6 mo | None | Pass |
|
|
76
|
+
| `watchdog` | `>=6.0.0,<7.0.0` | < 12 mo | None | Pass |
|
|
77
|
+
| `mcp` | `>=1.27.1,<2.0.0` | < 1 mo | None | Pass |
|
|
78
|
+
| `fastapi` | `>=0.136.1,<1.0.0` | < 1 mo | None | Pass |
|
|
79
|
+
| `uvicorn` | `>=0.46.0,<1.0.0` | < 1 mo | None | Pass |
|
|
80
|
+
| `apscheduler` | `>=3.11.2,<4.0.0` | < 12 mo | None | Pass |
|
|
81
|
+
| `pytest-asyncio` | `>=1.3.0,<2.0.0` | < 6 mo | None | Pass |
|
|
82
|
+
| `gitpython` | `>=3.1.50,<4.0.0` | < 6 mo | None | Pass |
|
|
83
|
+
| `neo4j` | `>=6.2.0,<7.0.0` | < 1 mo | None | Pass |
|
|
84
|
+
| `pydantic` | `>=2.13.4,<3.0.0` | < 1 mo | None | Pass |
|
|
85
|
+
| `psutil` | `>=6.1.1,<7.0.0` | < 1 mo | None | Pass |
|
|
86
|
+
|
|
87
|
+
## Post-v0.1.1 Roadmap (Next Milestone: v0.2.0)
|
|
88
|
+
1. **Multi-repo Support**: Allow a single watcher/server to manage multiple project knowledge graphs.
|
|
89
|
+
2. **Remote Transport**: Add HTTP/SSE transport for non-local agents.
|
|
90
|
+
3. **Symbol Navigation**: Direct 'jump-to-definition' tool for agents to retrieve actual code snippets from graph nodes.
|
|
91
|
+
4. **Visualisation**: Optional lightweight local web dashboard for graph exploration.
|
|
92
|
+
5. **Enhanced Decay**: Move from confidence linear decay to frequency-aware decay models.
|
memex_mcp-0.1.1/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.
|
memex_mcp-0.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: memex-mcp
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Developer context continuity system — temporal knowledge graph for AI coding agents, served via MCP. Inspired by Vannevar Bush's 1945 concept of a machine that remembers everything.
|
|
5
|
+
Project-URL: Homepage, https://github.com/STiFLeR7/memex
|
|
6
|
+
Project-URL: Repository, https://github.com/STiFLeR7/memex
|
|
7
|
+
Project-URL: Bug Tracker, https://github.com/STiFLeR7/memex/issues
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ai-agents,claude,context,developer-tools,gemini,knowledge-graph,mcp
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Requires-Dist: apscheduler<4.0.0,>=3.11.2
|
|
20
|
+
Requires-Dist: fastapi<1.0.0,>=0.136.1
|
|
21
|
+
Requires-Dist: gitpython<4.0.0,>=3.1.50
|
|
22
|
+
Requires-Dist: google-genai<3.0.0,>=2.0.1
|
|
23
|
+
Requires-Dist: graphiti-core[google-genai]<1.0.0,>=0.29.0
|
|
24
|
+
Requires-Dist: mcp<2.0.0,>=1.27.1
|
|
25
|
+
Requires-Dist: neo4j<7.0.0,>=6.2.0
|
|
26
|
+
Requires-Dist: psutil<7.0.0,>=6.1.1
|
|
27
|
+
Requires-Dist: pydantic<3.0.0,>=2.13.4
|
|
28
|
+
Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0
|
|
29
|
+
Requires-Dist: pytest-cov<8.0.0,>=7.1.0
|
|
30
|
+
Requires-Dist: pytest<10.0.0,>=9.0.3
|
|
31
|
+
Requires-Dist: python-dotenv<2.0.0,>=1.2.2
|
|
32
|
+
Requires-Dist: tree-sitter-language-pack<2.0.0,>=1.8.0
|
|
33
|
+
Requires-Dist: uvicorn<1.0.0,>=0.46.0
|
|
34
|
+
Requires-Dist: watchdog<7.0.0,>=6.0.0
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
<div align="center">
|
|
38
|
+
|
|
39
|
+
# memex-mcp
|
|
40
|
+
|
|
41
|
+
**A developer context continuity system that builds and maintains a temporal knowledge graph of your codebase.**
|
|
42
|
+
|
|
43
|
+
[](https://pypi.org/project/memex-mcp/)
|
|
44
|
+
[](https://www.npmjs.com/package/memex-mcp)
|
|
45
|
+
[](LICENSE)
|
|
46
|
+
[](https://github.com/STiFLeR7/memex/actions)
|
|
47
|
+
|
|
48
|
+

|
|
49
|
+
|
|
50
|
+
> *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.*
|
|
51
|
+
|
|
52
|
+
</div>
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## The problem
|
|
57
|
+
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
## How it works
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
┌──────────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
64
|
+
│ Your Repository │ ───► │ memex Watcher│ ───► │ Neo4j │
|
|
65
|
+
│ (Files + Git) │ │ (Tree-sitter)│ │ (Knowledge │
|
|
66
|
+
└──────────────────┘ └──────────────┘ │ Graph) │
|
|
67
|
+
└──────┬──────┘
|
|
68
|
+
│
|
|
69
|
+
▼
|
|
70
|
+
┌──────────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
71
|
+
│ AI Agent │ ◄─── │ MCP Server │ ◄────┤ Graphiti │
|
|
72
|
+
│ (Gemini/Claude) │ │ (stdio) │ │ Engine │
|
|
73
|
+
└──────────────────┘ └──────────────┘ └─────────────┘
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
## Installation
|
|
79
|
+
|
|
80
|
+
**via npx (no install required)**
|
|
81
|
+
```bash
|
|
82
|
+
npx memex-mcp init --repo .
|
|
83
|
+
npx memex-mcp watch --repo .
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**via pip / uv**
|
|
87
|
+
```bash
|
|
88
|
+
uv add memex-mcp
|
|
89
|
+
pip install memex-mcp
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**from source**
|
|
93
|
+
```bash
|
|
94
|
+
git clone https://github.com/STiFLeR7/memex
|
|
95
|
+
cd memex
|
|
96
|
+
uv sync
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Quickstart
|
|
100
|
+
|
|
101
|
+
**Prerequisites**: Python 3.11+, [uv](https://github.com/astral-sh/uv), Docker, and a Gemini API Key.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# 1. Start Neo4j infrastructure
|
|
105
|
+
docker-compose -f docker/docker-compose.yml up -d
|
|
106
|
+
|
|
107
|
+
# 2. Configure environment
|
|
108
|
+
# In your project root, create a .env file:
|
|
109
|
+
# NEO4J_URI=bolt://localhost:7687
|
|
110
|
+
# NEO4J_USER=neo4j
|
|
111
|
+
# NEO4J_PASSWORD=your_password
|
|
112
|
+
# GEMINI_API_KEY=your_api_key
|
|
113
|
+
|
|
114
|
+
# 3. Initialize and watch your repo
|
|
115
|
+
memex init --repo .
|
|
116
|
+
memex watch --repo .
|
|
117
|
+
|
|
118
|
+
# 4. Serve the MCP context (in a new terminal)
|
|
119
|
+
memex serve --repo .
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Connecting your agent
|
|
123
|
+
|
|
124
|
+
### Gemini CLI
|
|
125
|
+
Add to `~/.gemini/settings.json`:
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"mcpServers": {
|
|
129
|
+
"memex": {
|
|
130
|
+
"command": "npx",
|
|
131
|
+
"args": ["-y", "memex-mcp", "serve", "--repo", "."]
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Claude Code
|
|
138
|
+
Add to `.claude/settings.json`:
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"mcpServers": {
|
|
142
|
+
"memex": {
|
|
143
|
+
"type": "stdio",
|
|
144
|
+
"command": "npx",
|
|
145
|
+
"args": ["-y", "memex-mcp", "serve", "--repo", "."]
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Codex
|
|
152
|
+
Add to `~/.codex/config.toml`:
|
|
153
|
+
```toml
|
|
154
|
+
[mcp_servers.memex]
|
|
155
|
+
command = "npx"
|
|
156
|
+
args = ["-y", "memex-mcp", "serve", "--repo", "."]
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## MCP tools
|
|
160
|
+
|
|
161
|
+
### Read Tools (Context Retrieval)
|
|
162
|
+
| Tool | When to call it | Returns |
|
|
163
|
+
|------|-----------------|---------|
|
|
164
|
+
| `get_project_context` | At session start to get a project overview. | Markdown briefing of modules, decisions, and debt. |
|
|
165
|
+
| `get_symbol_context` | Before editing a specific function or class. | Signatures, callers, callees, and linked history. |
|
|
166
|
+
| `get_recent_decisions` | To understand recent architectural shifts. | Chronological list of tech decisions and rationales. |
|
|
167
|
+
| `get_open_problems` | To find technical debt or active bugs. | List of problems sorted by severity (Critical → Low). |
|
|
168
|
+
| `search_context` | For broad discovery across all node types. | Hybrid search results (semantic + keyword + graph). |
|
|
169
|
+
| `get_stale_context` | To identify potentially outdated documentation. | Report of edges with low confidence scores. |
|
|
170
|
+
|
|
171
|
+
### Write Tools (Graph Compounding)
|
|
172
|
+
| Tool | When to call it | Returns |
|
|
173
|
+
|------|-----------------|---------|
|
|
174
|
+
| `record_decision` | After making a technical or architectural choice. | Confirmation with the new Decision ID. |
|
|
175
|
+
| `record_problem` | When discovering a bug or technical debt item. | Confirmation with the new Problem ID. |
|
|
176
|
+
| `resolve_problem` | When a tracked problem has been fixed. | Confirmation of closure and session link. |
|
|
177
|
+
| `invalidate_edge` | When identifying a stale or incorrect fact. | Confirmation of edge invalidation. |
|
|
178
|
+
|
|
179
|
+
## How the graph works
|
|
180
|
+
|
|
181
|
+
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.
|
|
182
|
+
|
|
183
|
+
## Releasing
|
|
184
|
+
|
|
185
|
+
1. Add `PYPI_API_TOKEN` to GitHub repo secrets (Settings → Secrets → Actions)
|
|
186
|
+
2. Add `NPM_TOKEN` to GitHub repo secrets
|
|
187
|
+
3. Push a tag `git tag v0.1.2 && git push origin --tags` to trigger both publishes automatically
|
|
188
|
+
|
|
189
|
+
## Inspiration
|
|
190
|
+
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.
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
MIT - [STiFLeR7](https://github.com/STiFLeR7)
|
|
@@ -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/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 memex-mcp init --repo .
|
|
47
|
+
npx 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", "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", "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", "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)
|
|
Binary file
|