{"id":"6824d628-d697-41f8-855c-e0a218862e95","slug":"vndee-memex","kind":"mcp","name":"memex","summary":"Local-first temporal knowledge graph memory for AI agents. Runs with Ollama — no API keys required. Single Go binary + SQLite. Hybrid search, MCP server, REST API, interactive TUI.","owner":"vndee","repoUrl":"https://github.com/vndee/memex","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-06T06:45:39.000Z","addedAt":"2026-10-21T04:25:01.578Z","logoUrl":"https://avatars.githubusercontent.com/u/28271488?u=5bc792bd63391b3a5986e1996fc191867f55ff26&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","search","databases"],"tags":["ai-agents","embeddings","golang","knowledge-base","knowledge-graph","llm","memory","rag"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T04:28:11.719Z","sample":false,"url":"https://conduits.dev/tools/vndee-memex","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Memex\n\nA **local-first** temporal knowledge graph memory layer for AI agents. Single Go binary, zero dependencies beyond SQLite. Runs entirely on your machine with Ollama — no API keys required.\n\nInspired by Vannevar Bush's 1945 vision of a personal knowledge machine, Memex gives AI agents persistent, searchable, graph-structured memory with temporal awareness.\n\n![Knowledge Browser](assets/001.png)\n![Hybrid Search Results](assets/002.png)\n![Interactive Graph Explorer](assets/003.png)\n\n## Features\n\n- **Local-first and private** - Runs as a single Go binary with embedded SQLite, works out of the box with Ollama, and keeps data on your machine.\n- **Flexible model providers** - Supports Ollama (local), OpenAI, Gemini, Vertex AI, Azure, and Groq, with per-knowledge-base model and credential isolation.\n- **Low-cost ingestion pipeline** - Uses zero-LLM rule-based extraction for structured signals (errors, commits, config changes), with LLM fallback for rich text.\n- **Automatic memory capture** - Learns passively via editor hooks (`PostToolUse`, `PreCompact`, `UserPromptSubmit`) and records feedback/corrections for closed-loop improvement.\n- **Temporal knowledge graph core** - Builds entities, relations, and episodes with 3-tier entity resolution, bitemporal modeling, and relation strengthening instead of duplicate edges.\n- **Advanced graph retrieval** - Full N-hop subgraph extraction, Personalized PageRank scoring, weight-aware traversal, edge-type filtering, community-seeded expansion, temporal path queries, and graph-to-text summarization for richer LLM context.\n- **Hybrid retrieval and lifecycle** - Combines BM25 + vector + graph traversal with RRF, plus decay, pruning, and consolidation to keep memory relevant over time.\n- **Multiple interfaces** - Includes a full MCP server (25 tools), HTTP API (20+ endpoints), and a 3-pane Bubble Tea TUI with graph explorer.\n- **Operationally ready** - Provides async ingestion jobs with retries and one-command editor integration via `memex init` (Claude Code, Cursor, Windsurf, VS Code, Zed).\n\n## Quick Start\n\n```bash\n# Build\ngo build -o memex ./cmd/memex/\n\n# Auto-configure your AI editors (Claude Code, Cursor, Windsurf, VS Code, Zed)\n./memex init\n\n# Create a knowledge base with local Ollama (no API keys needed)\n# Requires: ollama pull nomic-embed-text && ollama pull llama3.2\n./memex kb create my-project --name \"My Project\"\n\n# Or use a cloud provider\n./memex kb create my-project \\\n  --embed gemini/gemini-embedding-001 \\\n  --llm gemini/gemini-2.5-flash \\\n  --name \"My Project\"\n\n# Store memories (rule-based extraction for errors/commits, LLM for rich text)\n./memex store \"Alice is a senior engineer working on Project Atlas\" --kb my-project\n./memex store \"Project Atlas uses Kafka and targets Q3 completion\" --kb my-project\n\n# Search\n./memex search \"who works on Atlas?\" --kb my-project\n\n# Search with advanced graph options\n./memex search \"who works on Atlas?\" --kb my-project \\\n  --graph-scorer pagerank --edge-types works_on,knows --expand-communities\n\n# Traverse the graph from a specific entity\n./memex graph <entity-id> --kb my-project --hops 3 --format text\n\n# Launch the TUI\n./memex tui\n\n# Start the MCP server (for Claude, Cursor, etc.)\n./memex mcp\n\n# Start the HTTP API\n./memex serve\n```\n\n## Architecture\n\n```\nText Input\n    |\n    v\n+-----------+     +-------------+      +-------------+      +-----------+     +-------------+\n| Ingestion | --> | Rule-Based  | -?-> | LLM Extract | ---> | Entity    | --> | Relation    |\n| Queue     |     | Extract     |      | (fallback)  |      | Resolution|     | Upsert &    |\n|           |     | (zero cost) |      |             |      | & Merge   |     | Strengthen  |\n+-----------+     +-------------+      +-------------+      +-----------+     +-------------+\n                                                              |\n                                                              v\n                                                      +---------------+\n                                                      | Embed & Store |\n                                                      | (SQLite +     |\n                                                      |  vec index)   |\n                                                      +---------------+\n                                                              |\n                  +-------------------------------------------+\n                  |               |               |\n                  v               v               v\n            +-----------+   +-----------+   +----------------------+\n            | BM25 FTS  |   | Vector    |   | Graph Traversal      |\n            | Search    |   | Search    |   | (BFS / PageRank /    |\n            +-----------+   +-----------+   |  Weighted / Temporal)|\n                  |               |         +----------------------+\n                  |               |               |\n                  +-------+-------+-------+-------+\n                          |               |\n                          v               v\n                    +----------+   +-----------+\n                    | RRF      |   | Community |\n                    | Fusion   |   | Expansion |\n                    +----------+   +-----------+\n```\n\n## How Memory Strengthening Works\n\nWhen the same fact is ingested multiple times, Memex recognizes existing relations and strengthens them rather than creating duplicates:\n\n```bash\n./memex store \"Alice works on Project Atlas\" --kb my-project\n# Creates: Alice --[WORKS_ON, weight=0.50]--> Project Atlas\n\n./memex store \"Alice is working on the Atlas project\" --kb my-project\n# Strengthens: Alice --[WORKS_ON, weight=0.75]--> Project Atlas (not a duplicate)\n```\n\nWeights are combined using probability union: `w = 1 - (1-a)(1-b)`, bounded to [0, 1] and monotonically increasing with each observation. This means frequently mentioned facts become high-confidence edges in the graph.\n\nDuring lifecycle management:\n- **Consolidation** merges duplicate entities and deduplicates any resulting duplicate edges\n- **Pruning** deduplicates fragmented relations before deleting — combined weight may exceed the prune threshold, saving them from deletion\n\n## Graph Retrieval\n\nMemex exposes the knowledge graph directly, giving agents rich structural context beyond keyword and vector search.\n\n### Subgraph Extraction\n\nRetrieve the full N-hop ego-graph around any entity as structured JSON or natural language text:\n\n```bash\n# JSON subgraph (nodes + edges with metadata)\n./memex graph <entity-id> --kb my-project --hops 3\n\n# Natural language summary for LLM context\n./memex graph <entity-id> --kb my-project --hops 2 --format text\n```\n\nText output is designed for direct injection into LLM prompts:\n\n```\nContext from knowledge graph:\n\nAlice (person, seed): Software engineer at Acme\n  - works_on Project Atlas [weight: 0.90, since 2025-01-15]\n  - knows Bob [weight: 0.75, since 2025-02-01]\n\nProject Atlas (project, 1 hop): Internal platform for data processing\n  - uses Kafka [weight: 0.85, since 2025-01-20]\n```\n\n### Graph Scoring Strategies\n\nControl how the graph channel ranks entities during hybrid search:\n\n| Scorer | Flag | Description |\n|--------|------|-------------|\n| **BFS** (default) | `--graph-scorer bfs` | Score = `1/hops`. Closer neighbors rank higher. |\n| **PageRank** | `--graph-scorer pagerank` | Personalized PageRank from seed nodes. Hub entities rank higher. |\n| **Weighted** | `--graph-scorer weighted` | Cumulative edge-weight product along path. High-confidence paths dominate. |\n\n### Filtering & Temporal Queries\n\n```bash\n# Only traverse specific relation types\n./memex search \"Atlas\" --kb my-project --edge-types works_on,manages\n\n# Only traverse edges with weight >= 0.5\n./memex search \"Atlas\" --kb my-project --graph-scorer weighted --min-weight 0.5\n\n# Expand seeds with their community members before graph traversal\n./memex search \"Atlas\" --kb my-project --expand-communities\n\n# Query the graph as it was at a specific point in time\n./memex search \"Atlas\" --kb my-project --at \"2025-06-01T00:00:00Z\"\n```\n\n## Providers\n\n| Provider | Embeddings | LLM | Config prefix |\n|----------|-----------|-----|---------------|\n| Ollama | nomic-embed-text, etc. | llama3.2, etc. | `ollama/` |\n| OpenAI | text-embedding-3-small | gpt-4o-mini | `openai/` |\n| Google Gemini | gemini-embedding-001 | gemini-2.5-flash | `gemini/` |\n| Vertex AI | textembedding-gecko | gemini-2.5-flash | `vertex/` |\n| Azure OpenAI | text-embedding-3-small | gpt-4o-mini | `azure/` |\n| Groq | -- | llama-3.3-70b | `groq/` |\n\n## CLI Reference\n\n```\nmemex version                              Print version\nmemex init [--editor <name>] [--dry-run]   Auto-configure AI editors\nmemex hook <post|compact|prompt> [flags]   Process hook events from editors\nmemex kb create <id> [flags]               Create a knowledge base\nmemex kb list [flags]                      List knowledge bases\nmemex kb delete <id> [flags]               Delete a knowledge base\nmemex store <text> --kb <id> [flags]       Store a memory\nmemex search <query> --kb <id> [flags]     Hybrid search\nmemex graph <entity_id> --kb <id> [flags]  Traverse graph from entity\nmemex jobs [--kb <id>] [--status <s>]      List ingestion jobs\nmemex stats [--kb <id>] [flags]            Show statistics\nmemex serve [flags]                        Start HTTP API server\nmemex mcp [flags]                          Start MCP server (stdio)\nmemex tui [flags]                          Launch interactive terminal UI\n```\n\n### KB Creation Flags\n\n```\n--embed <provider/model>    Embedding provider and model (default: ollama/nomic-embed-text)\n--llm <provider/model>      LLM provider and model (default: ollama/llama3.2)\n--name <name>               Display name\n--desc <description>        Description\n--db <path>                 Database path (default: ~/.memex/memex.db)\n```\n\n### Search Flags\n\n```\n--mode <hybrid|bm25|vector>     Search mode (default: hybrid)\n--top-k <n>                     Max results (default: 10)\n--hops <n>                      Graph BFS depth, 1-10 (default: 2)\n--graph-scorer <bfs|pagerank|weighted>  Graph scoring strategy (default: bfs)\n--edge-types <type1,type2>      Restrict traversal to these relation types\n--min-weight <f>                Min edge weight for weighted scorer (default: 0)\n--expand-communities            Expand seeds with community members\n--at <RFC3339>                  Temporal filter: only traverse edges valid at this time\n--json                          Output as JSON\n```\n\n### Graph Traverse Flags\n\n```\n--hops <n>                      Traversal depth, 1-10 (default: 2)\n--edge-types <type1,type2>      Restrict traversal to these relation types\n--format <json|text>            Output format (default: json)\n```\n\n## MCP Integration\n\nThe fastest way to set up is with `memex init`:\n\n```bash\n./memex init           # Auto-detects and configures all installed editors\n./memex init --dry-run # Preview changes without writing\n```\n\nOr manually add to your editor's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"command\": \"/path/to/memex\",\n      \"args\": [\"mcp\", \"--db\", \"/path/to/memex.db\"]\n    }\n  }\n}\n```\n\n### MCP Tools (25)\n\n**Memory & Search**\n| Tool | Description |\n|------|-------------|\n| `memex_store` | Store a memory (rule-based or LLM extraction) |\n| `memex_search` | Hybrid search (BM25 + vector + graph). Supports `max_hops`, `graph_scorer` (bfs/pagerank/weighted), `edge_types`, `min_weight`, `expand_communities`, and temporal `at` params. |\n\n**Graph Traversal**\n| Tool | Description |\n|------|-------------|\n| `memex_graph_traverse` | Traverse the knowledge graph from a seed entity, returning an N-hop subgraph. Supports `edge_types` filtering, temporal `at` queries, and `format` (json/text). |\n\n**Knowledge Bases**\n| Tool | Description |\n|------|-------------|\n| `memex_kb_create` | Create a new knowledge base |\n| `memex_kb_list` | List all knowledge bases |\n| `memex_kb_get` | Get a specific knowledge base |\n| `memex_kb_delete` | Delete a knowledge base |\n\n**Entities & Relations**\n| Tool | Description |\n|------|-------------|\n| `memex_entities` | List or search entities |\n| `memex_entity_get` | Get entity by ID |\n| `memex_relations` | Get relations for an entity |\n| `memex_relation_get` | Get relation by ID |\n| `memex_delete` | Delete entity, relation, or episode |\n\n**Episodes & Communities**\n| Tool | Description |\n|------|-------------|\n| `memex_episode_list` | List stored episodes |\n| `memex_episode_get` | Get episode by ID |\n| `memex_community_list` | List entity communities |\n\n**Feedback (Closed-Loop Learning)**\n| Tool | Description |\n|------|-------------|\n| `memex_feedback_record` | Record a correction when AI gets something wrong |\n| `memex_feedback_search` | Search past corrections to avoid repeating mistakes |\n| `memex_feedback_stats` | Get feedback statistics by topic |\n\n**Lifecycle & Stats**\n| Tool | Description |\n|------|-------------|\n| `memex_stats` | Get knowledge base statistics |\n| `memex_lifecycle_decay` | Run memory decay |\n| `memex_lifecycle_prune` | Prune weak memories |\n| `memex_lifecycle_consolidate` | Merge duplicate entities |\n\n**Jobs**\n| Tool | Description |\n|------|-------------|\n| `memex_job_list` | List ingestion jobs |\n| `memex_job_get` | Get job details |\n| `memex_job_retry` | Retry a failed job |\n\n## HTTP API\n\nStart with `memex serve --host 127.0.0.1 --port 8080`.\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/health` | Health check |\n| GET | `/api/v1/jobs` | List jobs (query: `kb`, `status`, `limit`) |\n| GET | `/api/v1/jobs/{id}` | Get job details |\n| POST | `/api/v1/jobs/{id}/retry` | Retry a failed job |\n| POST | `/api/v1/kb` | Create KB |\n| GET | `/api/v1/kb` | List KBs |\n| GET | `/api/v1/kb/{id}` | Get KB |\n| DELETE | `/api/v1/kb/{id}` | Delete KB |\n| POST | `/api/v1/kb/{id}/store` | Store memory |\n| POST | `/api/v1/kb/{id}/search` | Hybrid search (query: `max_hops`, `graph_scorer`, `edge_types`, `min_weight`, `expand_communities`, `at`) |\n| GET | `/api/v1/kb/{id}/entities` | List entities |\n| GET | `/api/v1/kb/{id}/entities/{eid}` | Get entity |\n| DELETE | `/api/v1/kb/{id}/entities/{eid}` | Delete entity |\n| GET | `/api/v1/kb/{id}/relations` | List relations |\n| GET | `/api/v1/kb/{id}/episodes` | List episodes |\n| GET | `/api/v1/kb/{id}/communities` | List communities |\n| GET | `/api/v1/kb/{id}/graph/traverse` | Traverse graph from entity (query: `entity_id`, `hops`, `edge_types`, `format`, `at`) |\n| POST | `/api/v1/kb/{id}/feedback` | Record feedback |\n| GET | `/api/v1/kb/{id}/feedback` | List/search feedback |\n| GET | `/api/v1/kb/{id}/feedback/stats` | Feedback statistics |\n| GET | `/api/v1/kb/{id}/stats` | Get stats |\n| POST | `/api/v1/kb/{id}/decay` | Run decay |\n| POST | `/api/v1/kb/{id}/prune` | Run prune |\n| POST | `/api/v1/kb/{id}/consolidate` | Run consolidation |\n\n## Hook-Based Auto-Capture\n\nMemex can passively learn from your AI editor sessions via hooks. When configured, it automatically:\n\n- **PostToolUse**: Extracts entities from tool outputs (bash errors, git commits, etc.) using zero-cost rule-based extraction\n- **PreCompact**: Saves important context before the editor compresses its conversation history\n- **UserPromptSubmit**: Injects relevant memories into each new prompt\n\n```bash\n# Process tool output (reads from stdin)\necho \"error: permission denied\" | ./memex hook post --kb my-project\n\n# Save transcript before context compression\ncat transcript.txt | ./memex hook compact --kb my-project\n\n# Inject relevant memories for a prompt\necho \"How do I fix the auth bug?\" | ./memex hook prompt --kb my-project\n```\n\nHooks are automatically configured when you run `memex init` for supported editors.\n\n## Terminal UI\n\nLaunch with `memex tui`. Vim-style navigation:\n\n| Key | Action |\n|-----|--------|\n| `h`/`l` | Switch panes (KB, Content, Inspector) |\n| `j`/`k` | Navigate items |\n| `g`/`G` | Jump to first/last |\n| `/` | Search |\n| `i` | Insert memory |\n| `n` | Create new KB (wizard) |\n| `e`/`r`/`p`/`J` | Switch collection (entities/relations/episodes/jobs) |\n| `V` | Graph explorer |\n| `x`/`d` | Delete item/KB |\n| `s` | Stats |\n| `?` | Help |\n\n## Development\n\n```bash\n# Build\ngo build -o memex ./cmd/memex/\n\n# Run tests\ngo test ./...\n\n# Run with verbose logging\nMEMEX_LOG=debug ./memex tui\n\n# Seed example data\nexport GEMINI_API_KEY=\"your-key\"\n./examples/seed.sh\n```\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n"}