{"id":51525535,"url":"https://github.com/stifler7/memex","last_synced_at":"2026-07-08T21:01:04.188Z","repository":{"id":356912572,"uuid":"1233986887","full_name":"STiFLeR7/memex","owner":"STiFLeR7","description":"Persistent memory for AI coding agents via MCP — a bitemporal knowledge graph of your codebase, served to Claude Code, Cursor, Gemini CLI, and any MCP client. Tree-sitter + Gemini Flash → Neo4j (via Graphiti). 12 MCP tools, hierarchical clusters, two-regime confidence decay.","archived":false,"fork":false,"pushed_at":"2026-07-02T06:52:14.000Z","size":3299,"stargazers_count":11,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-02T08:21:30.585Z","etag":null,"topics":["agent-memory","ai-agents","ai-coding-assistant","anthropic","claude-code","code-intelligence","codex","context-engineering","gemini","gemini-cli","graphiti","knowledge-graph","mcp","mcp-server","model-context-protocol","neo4j","persistent-memory","rag","temporal-graph","tree-sitter"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/memex-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/STiFLeR7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"AUDIT.md","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T15:50:20.000Z","updated_at":"2026-07-02T06:52:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/STiFLeR7/memex","commit_stats":null,"previous_names":["stifler7/memex"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/STiFLeR7/memex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2Fmemex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2Fmemex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2Fmemex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2Fmemex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/STiFLeR7","download_url":"https://codeload.github.com/STiFLeR7/memex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2Fmemex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35278166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","ai-coding-assistant","anthropic","claude-code","code-intelligence","codex","context-engineering","gemini","gemini-cli","graphiti","knowledge-graph","mcp","mcp-server","model-context-protocol","neo4j","persistent-memory","rag","temporal-graph","tree-sitter"],"created_at":"2026-07-08T21:01:03.223Z","updated_at":"2026-07-08T21:01:04.171Z","avatar_url":"https://github.com/STiFLeR7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# memex — temporal knowledge graph memory for AI coding agents\n\n\u003c!-- mcp-name: io.github.STiFLeR7/memex --\u003e\n\n\u003e Persistent memory and codebase context for AI coding agents, served over MCP. A bitemporal knowledge graph of your repository — modules, symbols, decisions, problems — for Claude Code, Cursor, Codex, Gemini CLI, and any MCP-compatible agent.\n\nA daemon and MCP server that turns every commit and every file change into structured graph state: modules, symbols, decisions, problems, lockfile facts. Sessions stop starting blind. Agents stop re-discovering the same refactor every time you `/clear`.\n\n[![PyPI](https://img.shields.io/pypi/v/memex-mcp?v=0.3.3)](https://pypi.org/project/memex-mcp/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/memex-mcp)](https://pypistats.org/packages/memex-mcp)\n[![npm](https://img.shields.io/npm/v/stifler-memex-mcp?v=0.3.3)](https://www.npmjs.com/package/stifler-memex-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/stifler-memex-mcp)](https://www.npmjs.com/package/stifler-memex-mcp)\n[![Claude Code marketplace](https://img.shields.io/badge/Claude%20Code-marketplace-7c3aed)](https://github.com/STiFLeR7/claude-plugins)\n[![memex MCP server](https://glama.ai/mcp/servers/STiFLeR7/memex/badges/score.svg)](https://glama.ai/mcp/servers/STiFLeR7/memex)\n[![GitHub stars](https://img.shields.io/github/stars/STiFLeR7/memex?style=flat)](https://github.com/STiFLeR7/memex/stargazers)\n[![Tests](https://github.com/STiFLeR7/memex/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/STiFLeR7/memex/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/STiFLeR7/memex/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/STiFLeR7/memex/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/STiFLeR7/memex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/STiFLeR7/memex)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n![memex — temporal knowledge graph MCP server for AI coding agents, built on Graphiti and Neo4j](https://raw.githubusercontent.com/STiFLeR7/memex/master/assets/memex.png)\n\n```mermaid\nflowchart LR\n    A[Your repository\u003cbr/\u003efiles + git] --\u003e B[memex watcher\u003cbr/\u003etree-sitter + Gemini]\n    B --\u003e C[Neo4j graph\u003cbr/\u003ebitemporal facts]\n    C --\u003e D[MCP server\u003cbr/\u003estdio / HTTP]\n    D --\u003e E[AI agent\u003cbr/\u003eClaude · Cursor · Codex · Gemini CLI]\n    E -.-\u003e|writes decisions back| C\n\n    style B fill:#cfe8ff,stroke:#0066cc,color:#000\n    style C fill:#fff4cf,stroke:#cc9900,color:#000\n    style E fill:#d4f5d4,stroke:#2d8f2d,color:#000\n```\n\n## Install\n\n### Via Claude Code marketplace\n\n```\n/plugin marketplace add STiFLeR7/claude-plugins\n/plugin install memex-mcp@stifler-marketplace\n```\n\nRestart your Claude Code session.\n\n### Manual\n\n```bash\ndocker compose -f docker/docker-compose.yml up -d\ncat \u003e .env \u003c\u003cEOF\nNEO4J_URI=bolt://localhost:7687\nNEO4J_USER=neo4j\nNEO4J_PASSWORD=memex-local\nGEMINI_API_KEY=your-key-here\nEOF\nnpx stifler-memex-mcp init --repo .\nnpx stifler-memex-mcp watch --repo .\nnpx stifler-memex-mcp serve --repo .\n```\n\n| Channel | Command |\n|---|---|\n| Claude Code marketplace | `/plugin install memex-mcp@stifler-marketplace` |\n| npx (no install) | `npx stifler-memex-mcp \u003ccmd\u003e` |\n| uv | `uv add memex-mcp` |\n| pip | `pip install memex-mcp` |\n| source | `git clone github.com/STiFLeR7/memex \u0026\u0026 uv sync` |\n\n## At a glance\n\n| Property | Value |\n|---|---|\n| Output | A Neo4j graph populated continuously from your repo |\n| Storage | Neo4j via [Graphiti](https://github.com/getzep/graphiti). Bitemporal — every edge has `created_at` and optional `expired_at` |\n| Survives | `/clear`, terminal crashes, machine restarts, teammate handoffs |\n| Hands off to | Claude Code, Cursor, Codex, Gemini CLI, any MCP client |\n| Granularity | Scales from 50 to 5000+ modules via hierarchical Leiden clusters |\n| Synthesis | Gemini Flash distills commits into `Decision` nodes; Pro for grounded synthesis |\n| Confidence | Computed at query time. Two-regime decay (validated half-life ~139d, unvalidated stale at 30d) |\n| Write governance | Per-node-type ACL, intent-confirmation on agent writes, explicit `corroborates` / `supersedes` semantics |\n| Tests | 333 passing, ~93% coverage |\n\n## The lifecycle\n\n```mermaid\nflowchart TD\n    Init[memex init\u003cbr/\u003eextract baseline] --\u003e Watch[memex watch\u003cbr/\u003edaemon + git hooks]\n    Watch --\u003e|commit| Extract[tree-sitter extract\u003cbr/\u003esymbols, imports, lockfile]\n    Extract --\u003e Synth[Gemini Flash\u003cbr/\u003ediff → Decision nodes]\n    Synth --\u003e Write[Graphiti add_episode\u003cbr/\u003e+ post-hoc bitemporal SET]\n    Write --\u003e Decay[Scheduler\u003cbr/\u003enightly confidence decay]\n    Decay --\u003e|stale edges| Archive[expired_at = now]\n\n    Serve[memex serve\u003cbr/\u003eMCP stdio/HTTP] -.-\u003e|reads| Write\n    Agent[AI agent] --\u003e|14 MCP tools| Serve\n    Serve --\u003e|record_decision / record_problem| Write\n\n    Cluster[memex cluster\u003cbr/\u003eLeiden over hybrid edges] -.-\u003e|every N commits| Write\n\n    style Init fill:#e8f4ff,color:#000\n    style Watch fill:#fff4cf,color:#000\n    style Synth fill:#ffe0cc,color:#000\n    style Serve fill:#d4f5d4,color:#000\n```\n\n## MCP tools\n\n14 tools — eight read, four write, two analytic.\n\n### Read\n\n| Tool | When |\n|---|---|\n| `get_project_context` | Session start. Returns a cluster-level briefing under 1500 tokens regardless of repo size |\n| `get_symbol_context` | Before editing a function or class. Returns callers, callees, linked decisions |\n| `get_recent_decisions` | Last N days of architectural decisions, optionally module-scoped |\n| `get_open_problems` | Active bugs and tech debt, sorted by severity |\n| `search_context` | Hybrid search: semantic × keyword × graph traversal × RRF merge |\n| `get_stale_context` | Edges whose composite confidence dropped below threshold |\n| `explain_change` | Given a commit SHA, cross-references the diff with linked Decision/Problem nodes and asks Gemini Pro for a grounded explanation |\n| `predict_impact` | Given a file path, returns a ranked list of modules likely affected based on graph coupling (no LLM call) |\n\n### Write\n\n| Tool | When |\n|---|---|\n| `record_decision` | After making a technical choice. Supports `corroborates` (reinforce) and `supersedes` (replace) |\n| `record_problem` | When discovering a bug or piece of tech debt |\n| `resolve_problem` | When a tracked problem is fixed |\n| `invalidate_edge` | When a stored fact is no longer true |\n\n## Bitemporal confidence\n\nConfidence 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.\n\n```mermaid\nflowchart LR\n    Edge[Edge created\u003cbr/\u003ebase_confidence] --\u003e Q{Validated by\u003cbr/\u003ea human?}\n    Q --\u003e|yes| Slow[Slow regime\u003cbr/\u003ehalf-life ~139d]\n    Q --\u003e|no| Fast[Fast regime\u003cbr/\u003estale at exactly 30d]\n    Slow --\u003e Score[Composite score\u003cbr/\u003econf × recency × rehearsal]\n    Fast --\u003e Score\n    Score --\u003e|below floor| Stale[get_stale_context surfaces it]\n    Score --\u003e|access| Bump[last_reinforced_at updated]\n    Bump --\u003e Score\n\n    style Slow fill:#d4f5d4,color:#000\n    style Fast fill:#ffd4d4,color:#000\n```\n\n| Property | Value |\n|---|---|\n| Validated half-life | ~139 days |\n| Unvalidated stale threshold | 30 days (composite \u003c 0.3) |\n| Recency τ | 90 days (exponential decay) |\n| Composite formula | `conf × recency × (1 + rehearsal_w × log(1 + access_count))` |\n| Conflict similarity threshold | 0.4 (below this + overlapping validity = conflict) |\n| Intent-confirmation threshold | 0.85 (MCP write similarity check) |\n\n## Hierarchical clusters\n\n`memex cluster` runs hierarchical Leiden over a hybrid edge graph:\n\n| Edge type | Weight |\n|---|---|\n| Directory co-location | 1.0 |\n| Module imports | 2.0 |\n| Symbol calls | `log(1 + calls)` |\n\n| Property | Value |\n|---|---|\n| Algorithm | `graspologic.partition.hierarchical_leiden` with fixed seed |\n| Naming | TF-IDF top-3 over module docstrings + symbol names, parent-dir fallback |\n| ID pinning | Jaccard ≥ 0.5 across reruns (cluster names stay stable through renames) |\n| User overrides | `.memex/clusters.yaml` — any assignment can be locked |\n| Context budget | `get_project_context` stays under 1500 tokens whether your repo has 50 or 5000 modules |\n\n## Measure Your Savings\n\nmemex tracks token reduction metrics and human review actions locally in a SQLite database (`~/.config/memex/telemetry.db`). \n\nYou can query your savings at any time using the CLI:\n```bash\nmemex stats\n```\n\nOr view the raw JSON payload:\n```bash\nmemex stats --json\n```\n\nOr target a specific repository scope:\n```bash\nmemex stats --repo /path/to/repo\n```\n\nThis returns an aggregation of:\n- **Period Summaries**: Calls, tokens returned, naive tokens (size of files requested), tokens saved, and token reduction percentage across `today`, `last 7 days`, `last 30 days`, and `lifetime`.\n- **Top Tools**: The most valuable tools sorted by total tokens saved.\n- **Agent Clients**: Active agents (Claude Code, Gemini CLI, Cursor, Codex) and their token saving distribution.\n- **Validation Health**: Total validated, unvalidated, and corroborated nodes, along with the elapsed days since the last review.\n\nThe same statistics are exposed via the HTTP MCP transport:\n```http\nGET /stats?repo=/path/to/repo\nAuthorization: Bearer \u003cyour-key\u003e\n```\n\n## Connect your agent\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\nMarketplace install above does this for you. Manual wiring in `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"stifler-memex-mcp\", \"serve\", \"--repo\", \".\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"stifler-memex-mcp\", \"serve\", \"--repo\", \".\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"stifler-memex-mcp\", \"serve\", \"--repo\", \".\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodex\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.memex]\ncommand = \"npx\"\nargs = [\"-y\", \"stifler-memex-mcp\", \"serve\", \"--repo\", \".\"]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAnthropic memory tool (memory_20250818)\u003c/b\u003e\u003c/summary\u003e\n\nmemex can back Claude's native memory tool — agents read from a per-session graph projection plus a writable scratch zone.\n\n```bash\nmemex memory-tool serve --repo .                     # in-process\nmemex memory-tool serve --repo . --transport http    # FastAPI on :7464\n```\n\n```python\nfrom memex.memory_tool import MemexAsyncMemoryTool\nmemory_tool = MemexAsyncMemoryTool(repo_root=\".\")\nclient.beta.messages.run_tools(..., tools=[memory_tool])\n```\n\u003c/details\u003e\n\n## Operating principles\n\n| # | Principle | The bet |\n|---|---|---|\n| 1 | Bitemporal, never destructive | Edges are expired, not deleted. `WHERE r.expired_at IS NULL` filters live state |\n| 2 | Confidence is computed, not stored | Mutating a number invites silent drift. Recompute every read |\n| 3 | Two regimes for decay | Validated facts decay slowly; unvalidated facts must earn their place by being accessed |\n| 4 | Human in the loop | `memex review` queues lowest-confidence Decision nodes for explicit validation |\n| 5 | Write governance | Per-node-type ACL. `Decision.policy = open`, `Module.policy = locked`. Intent-confirmation on similar-content writes |\n| 6 | Tokens are budgeted | `get_project_context` stays under 1500 tokens at any repo size via Leiden clusters |\n| 7 | Synthesis only on commits | The watcher batches by debounce window. Gemini Flash is not in the hot path of a tool call |\n| 8 | Pro for synthesis, Flash for extraction | `explain_change` uses Pro because grounding matters. Everything else uses Flash |\n| 9 | Multi-repo aware | One watcher + one MCP server can manage hundreds of repos. `--repo` switches scope |\n| 10 | Local-first | Neo4j runs in your Docker. Gemini is the only outbound call, and only on commits |\n\n## When to use memex\n\n| Use it when | Skip it when |\n|---|---|\n| Multi-week or multi-month project | One-shot script, throwaway prototype |\n| You work across multiple agents (Claude, Cursor, Codex) and want shared context | You only ever pair with one agent on one task |\n| Architectural decisions are made over time and need to be remembered | The whole project fits in a single 200k-token context window |\n| You want to query \"what did we decide about X\" from any session | Your repo is already small enough to paste into the prompt |\n| Multiple developers using AI agents on the same codebase | Solo work where you never `/clear` |\n\n## Project structure\n\n```\nmemex/\n├── memex/\n│   ├── extractor/        tree-sitter + lockfile parsers\n│   ├── graph/            Neo4j writes, confidence, archive, cluster engine\n│   ├── synthesizer/      Gemini Flash → Decision nodes\n│   ├── mcp_server/       14 MCP tools (read + write + analytic)\n│   ├── memory_tool/      Anthropic memory_20250818 adapter\n│   ├── watcher/          daemon + git hooks\n│   └── cli.py            init / watch / serve / review / graph / cluster\n├── tests/                333 passing, ~93% coverage\n├── docker/               Neo4j compose\n├── npm/                  npx wrapper (publishes as stifler-memex-mcp)\n└── Dockerfile            introspection-only image for MCP directory sandboxes\n```\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `memex init` | Extract baseline graph state, run first cluster pass |\n| `memex watch` | Daemon that listens for file + git events and writes to Neo4j |\n| `memex serve` | Run the MCP server (stdio, HTTP, or both) |\n| `memex review` | TUI that walks lowest-confidence decisions for human validation |\n| `memex graph --output graph.html` | Self-contained D3 force layout with cluster overlays |\n| `memex cluster [--rerun] [--dry-run]` | Run Leiden over the hybrid edge graph; pin cluster IDs by Jaccard ≥ 0.5 |\n| `memex memory-tool serve` | Back Anthropic's `memory_20250818` tool with a graph projection |\n| `memex stats [--json] [--repo \u003cpath\u003e]` | Show context token savings and telemetry stats |\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n\n## Author\n\nHill Patel ([@STiFLeR7](https://github.com/STiFLeR7))\n\n## Core Contributors \u0026 Maintainers\n\n- Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7)) — architect, maintainer\n- Nirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05)) — lead contributor, maintainer\n\n## Contributing\n\nOpen an issue or PR. `uv sync --all-extras \u0026\u0026 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.\n\n\u003e *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.\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstifler7%2Fmemex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstifler7%2Fmemex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstifler7%2Fmemex/lists"}