{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/assets/banner.png\" alt=\"memex — long-term memory for AI coding agents\" width=\"720\">\n</p>\n\n**Stop re-explaining your stack every chat.** Long-term memory for AI coding agents — stored on your machine.\n\nmemex gives Cursor, Claude Desktop, and other MCP clients a memory that survives across chats. Save preferences, decisions, and facts once; the agent finds them again later. No cloud account, no API keys, no vector database to run.\n\n[![Unit Tests](https://github.com/kioie/memex/actions/workflows/unit.yml/badge.svg)](https://github.com/kioie/memex/actions/workflows/unit.yml)\n[![Integration Tests](https://github.com/kioie/memex/actions/workflows/integration.yml/badge.svg)](https://github.com/kioie/memex/actions/workflows/integration.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/kioie/memex/memex.svg)](https://pkg.go.dev/github.com/kioie/memex/memex)\n\n**Current release:** v0.6.0 · **Requires:** Go 1.26+\n\n---\n\n## When to use memex\n\n**Use memex if you:**\n\n- Code with **Cursor**, **Claude Desktop**, or any **MCP** client\n- Want preferences and project facts to **persist across chats**\n- Need memory **on your machine** — no vendor account or API keys\n- Are building or running an **agent** that should recall past context\n\n**Good fits — ask memex to remember things like:**\n\n| Situation | Example |\n|-----------|---------|\n| Coding preferences | \"Prefers Go, table-driven tests, no Python for services\" |\n| Project decisions | \"This repo uses SQLite; don't suggest Postgres\" |\n| Conventions | \"Branch names: `feature/…`, commits: conventional commits\" |\n| Agent commitments | \"Will add integration tests before merging\" |\n| Session start | Agent loads your prefs instead of re-interviewing you |\n\n**memex is not for:**\n\n- Passwords, API keys, or secrets\n- Full chat transcripts or log archival\n- Team-wide cloud memory synced across machines (local-first, per device)\n- Non-MCP apps (memex speaks MCP over stdio)\n\n**Agents:** if the user repeats themselves across sessions, or asks you to \"remember\" something durable — use memex. See [docs/FOR-AGENTS.md](docs/FOR-AGENTS.md).\n\n---\n\n## The outcome\n\n| Without memex | With memex |\n|---------------|------------|\n| Every new chat starts from zero | Agent recalls your stack, style, and past decisions |\n| You repeat the same preferences | You say it once; memex stores it locally |\n| Memory lives in a vendor's cloud | Memory lives in `~/.memex/memex.db` on your disk |\n| Extra services and API keys | `go install` + one MCP config line |\n\n---\n\n## Try it in 2 minutes\n\n```bash\ngo install github.com/kioie/memex/cmd/memex@latest\nmemex doctor    # confirm local store is ready\n```\n\nAdd to your MCP client (e.g. Cursor):\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": {\n      \"command\": \"memex\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nIn chat:\n\n> Remember that I prefer table-driven tests and Go over Python.\n\nOpen a **new chat**:\n\n> What are my testing preferences?\n\n**Full walkthrough:** [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)\n\n**Try in browser (no Cursor):** `npx @modelcontextprotocol/inspector memex serve`\n\n**Smithery:** [kioie/memex](https://smithery.ai/servers/kioie/memex) (local Docker via MCPB — no hosting) · Registry metadata in [`server.json`](server.json)\n\n---\n\n## How it works\n\n```\nYou or the agent          memex (local)              Later sessions\n      │                        │                           │\n      │  remember(\"prefers Go\")│                           │\n      │ ──────────────────────►│  saved to SQLite          │\n      │                        │                           │\n      │                        │  recall(\"testing prefs\")  │\n      │                        │ ◄─────────────────────────│\n      │                        │ ─────────────────────────►│ relevant facts\n```\n\n1. **Save** — `remember` stores a short fact (deduplicated per user)\n2. **Find** — `recall` or `retrieve_context` searches when the agent needs context\n3. **Update** — `update_memory` revises a fact; old versions stay in the audit trail\n\nData never leaves your machine unless you copy the database file.\n\n---\n\n## What you get\n\n| Feature | What it means for you |\n|---------|------------------------|\n| **Local storage** | SQLite file under `~/.memex` — you own it |\n| **Smart search** | Keyword search built in; optional `MEMEX_HYBRID=1` for paraphrase-friendly matching |\n| **Context limits** | `retrieve_context` returns only what fits your token budget |\n| **Safe updates** | Revising a fact keeps history; nothing is silently overwritten |\n| **Agent + user facts** | Track who said what (`source`: user / agent / system) |\n| **Multi-project scoping** | Separate by user, agent, session, or metadata tags |\n| **Built-in guidance** | MCP prompts teach agents when and how to use memory |\n| **Health check** | `memex doctor` shows path, counts, and config |\n\n---\n\n## Documentation\n\n| Doc | For |\n|-----|-----|\n| [Getting started](docs/GETTING-STARTED.md) | First-time setup in Cursor |\n| [For AI agents](docs/FOR-AGENTS.md) | When agents should read/write memory |\n| [Examples](examples/) | MCP configs and scoping recipes |\n| [All docs](docs/README.md) | Index |\n\n**Agents:** fetch MCP prompts `memory_guide`, `session_start`, and `remember_fact` from the connected server.\n\n---\n\n## Tools (10)\n\nEveryday use — you usually only need the first three:\n\n| Tool | Plain English |\n|------|---------------|\n| `remember` | Save a fact |\n| `retrieve_context` | Find relevant facts, sized for the model context window |\n| `recall` | Search by keywords (query required) |\n| `list_memories` | Browse stored facts without searching |\n| `update_memory` | Change an existing fact (keeps history) |\n| `get_memory` | Look up one fact by ID |\n| `forget` | Remove one fact (soft delete) |\n| `delete_memories` | Remove several facts |\n| `delete_all_memories` | Wipe a user's memories (`confirm=true`) |\n| `memory_history` | See how a fact changed over time |\n\n---\n\n## Settings\n\n| Variable | Purpose |\n|----------|---------|\n| `MEMEX_DIR` | Where to store data (default `~/.memex`) |\n| `MEMEX_USER_ID` | Your memory namespace (default `default`) |\n| `MEMEX_AGENT_ID` | Separate memories per agent |\n| `MEMEX_RUN_ID` | Tag memories to a session or run |\n| `MEMEX_HYBRID=1` | Turn on extra local matching for paraphrases |\n| `MEMEX_VERBOSE=1` | Log database path while debugging |\n\n---\n\n## Why memex?\n\nHosted memory products typically need API keys, cloud embeddings, and network calls on every recall. memex is the opposite: a small MCP server on your machine, writing distilled facts that **agents** choose to store — no extraction pipeline, no vendor lock-in.\n\n| | memex | Typical hosted memory |\n|---|-------|----------------------|\n| Setup | `go install` + MCP config | API keys, SDK, often Docker |\n| Data | Your disk | Vendor cloud |\n| Offline | Yes | Usually no |\n| Cost | Free (local compute only) | Usage-based |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/kioie/memex.git && cd memex\nmake test              # fast unit tests\nmake test-integration  # MCP stdio roundtrip\nmemex doctor\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [SECURITY.md](SECURITY.md)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 7263,
  "sha": "4ac2224bcebd45e5c1f180d21915ec3de61cc7bb99a7e8188f8a44404f140d1e",
  "repo_slug": "kioie/memex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kioie_memex_e1a05496/readme"
}