{
  "markdown": "# memex\n\nA local AI memory system for Claude Code and Cursor. Remembers your preferences, decisions, and context across sessions using a Go HTTP service and Qdrant vector database running in Docker. All data stays on your machine — nothing leaves.\n\n## How it works\n\n- At session start, relevant memories are automatically injected into Claude's context\n- During a session, Claude can save new memories via MCP tools\n- Every tool call is automatically traced — captured with input, output, duration, and reasoning\n- All data stays local — nothing leaves your machine\n- Any AI tool that supports MCP or HTTP can connect to the same memex instance and share memory\n\n## Why memex\n\n- **Cross-session memory** — preferences set today are available tomorrow\n- **Cross-platform memory** — Claude Code, Cursor, and local LLMs (e.g. Ollama) can all read and write to the same memory store. Save a preference in one tool, use it in another\n- **Accurate memory** — updating a preference deletes the old one first, so you never have conflicting memories\n- **Session tracer** — replay any past session: see every tool call, what it did, how long it took, and Claude's reasoning behind it\n- **Private** — runs entirely on your machine, no cloud involved\n\n## Requirements\n\n- [Docker](https://www.docker.com/) (with Docker Compose)\n- [Go 1.22+](https://go.dev/)\n- [Claude Code](https://claude.ai/code) or [Cursor](https://www.cursor.com/)\n\n## Installation\n\n**1. Clone and build**\n\n```bash\ngit clone https://github.com/Shvmvrshny/memex\ncd memex\ngo install ./cmd/memex\n```\n\n**2. Start the Docker stack**\n\n```bash\ndocker compose up -d\n```\n\nThis starts two containers:\n- `memex` — HTTP API on port `8765`\n- `qdrant` — vector database on port `6333`\n\n**3. Register the MCP server**\n\n**Claude Code:**\n```bash\nclaude mcp add --scope user memex ~/go/bin/memex mcp\n```\n\n**Cursor:** Go to `Cursor Settings → MCP` and add:\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"command\": \"/Users/your-username/go/bin/memex\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nRestart your editor. The `save_memory`, `search_memory`, `list_memories`, and `delete_memory` tools will be available in every session.\n\n**4. (Optional) Add hooks**\n\nHooks enable automatic memory injection at session start and full session tracing.\n\n**Claude Code** — add to `~/.claude/settings.json`:\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"memex hook session-start\" }] }\n    ],\n    \"SessionEnd\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"memex hook session-stop\", \"async\": true }] }\n    ],\n    \"PreToolUse\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"memex hook pre-tool-use\", \"async\": true }] }\n    ],\n    \"PostToolUse\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"memex hook post-tool-use\", \"async\": true }] }\n    ]\n  }\n}\n```\n\n- `SessionStart` — injects relevant memories into context at the start of each session\n- `PreToolUse` / `PostToolUse` — traces every tool call with input, output, and duration\n- `SessionEnd` — finalises the session trace and backfills Claude's reasoning from the transcript\n\n**Cursor** — the hook is included in the `.cursor-plugin/` directory and runs automatically when the plugin is installed.\n\n**5. (Optional) Open the tracer UI**\n\nAfter enabling the hooks and running a session, open `http://localhost:8765/ui/` to browse past sessions by project and replay every tool call in order.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `save_memory` | Save a preference, decision, or piece of context |\n| `search_memory` | Search memories by keyword |\n| `list_memories` | List all stored memories |\n| `delete_memory` | Delete a memory by ID (use before saving an updated preference) |\n\n## API\n\nThe HTTP service runs on `http://localhost:8765`.\n\n**Memory**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/health` | Health check |\n| `POST` | `/memories` | Save a memory |\n| `GET` | `/memories?context=<query>` | Search memories |\n| `DELETE` | `/memories/:id` | Delete a memory by ID |\n| `POST` | `/summarize` | Save a session summary |\n\n**Tracer**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/trace/event` | Record a tool call event |\n| `POST` | `/trace/stop` | Finalise a session (backfills reasoning from transcript) |\n| `GET` | `/trace/projects` | List all traced projects |\n| `GET` | `/trace/sessions?project=<name>` | List sessions for a project |\n| `GET` | `/trace/session/:id` | Get all events for a session |\n| `POST` | `/checkpoint` | Save a session summary as a high-importance memory |\n\n## Project structure\n\n```\nmemex/\n├── cmd/\n│   └── memex/\n│       └── main.go       # entry point\n├── internal/\n│   ├── config.go         # env config\n│   ├── models.go         # Memory, SaveMemoryRequest, SearchResponse\n│   ├── store.go          # Store interface\n│   ├── qdrant.go         # Qdrant REST client (memory collection)\n│   ├── handlers.go       # HTTP handlers (memory)\n│   ├── tracer_models.go  # TraceEvent, Session, TraceEventRequest\n│   ├── tracer.go         # TraceStore — Qdrant ops for traces collection\n│   ├── tracer_handlers.go# HTTP handlers (tracer)\n│   ├── transcript.go     # Claude transcript parser (reasoning backfill)\n│   ├── distill.go        # session summary distillation\n│   ├── server.go         # HTTP server setup\n│   ├── hook.go           # hook logic (session-start/stop, pre/post-tool-use)\n│   └── mcp.go            # MCP stdio server\n├── ui/                   # React tracer UI (Vite)\n├── plugin/               # Claude Code plugin manifest and skills\n├── Dockerfile\n└── docker-compose.yml\n```\n\n## Stopping\n\n```bash\ndocker compose down\n```\n\nTo reset all memories:\n\n```bash\ndocker compose down -v && docker compose up -d\n```\n",
  "bytes": 5803,
  "sha": "98e00c3eb8a9fa35a1bb6ce6e72abdba56bdd59f0ae85f00486d78fae9350b90",
  "repo_slug": "shvmvrshny/memex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_shvmvrshny_memex_memex_86d62d80/readme"
}