memex

<p align="center"> <img src="docs/assets/banner.png" alt="memex — long-term memory for AI coding agents" width="720"> </p>

Stop re-explaining your stack every chat. Long-term memory for AI coding agents — stored on your machine.

memex 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.

Current release: v0.6.0 · Requires: Go 1.26+

---

When to use memex

Use memex if you:

• Code with Cursor, Claude Desktop, or any MCP client
• Want preferences and project facts to persist across chats
• Need memory on your machine — no vendor account or API keys
• Are building or running an agent that should recall past context

Good fits — ask memex to remember things like:

Situation	Example
Coding preferences	"Prefers Go, table-driven tests, no Python for services"
Project decisions	"This repo uses SQLite; don't suggest Postgres"
Conventions	"Branch names: feature/…, commits: conventional commits"
Agent commitments	"Will add integration tests before merging"
Session start	Agent loads your prefs instead of re-interviewing you

memex is not for:

• Passwords, API keys, or secrets
• Full chat transcripts or log archival
• Team-wide cloud memory synced across machines (local-first, per device)
• Non-MCP apps (memex speaks MCP over stdio)

Agents: if the user repeats themselves across sessions, or asks you to "remember" something durable — use memex. See docs/FOR-AGENTS.md.

---

The outcome

Without memex	With memex
Every new chat starts from zero	Agent recalls your stack, style, and past decisions
You repeat the same preferences	You say it once; memex stores it locally
Memory lives in a vendor's cloud	Memory lives in ~/.memex/memex.db on your disk
Extra services and API keys	go install + one MCP config line

---

Try it in 2 minutes

go install github.com/kioie/memex/cmd/memex@latest
memex doctor    # confirm local store is ready

Add to your MCP client (e.g. Cursor):

{
  "mcpServers": {
    "memex": {
      "command": "memex",
      "args": ["serve"]
    }
  }
}

In chat:

Remember that I prefer table-driven tests and Go over Python.

Open a new chat:

What are my testing preferences?

Full walkthrough: docs/GETTING-STARTED.md

Try in browser (no Cursor): npx @modelcontextprotocol/inspector memex serve

Smithery: kioie/memex (local Docker via MCPB — no hosting) · Registry metadata in server.json

---

How it works

You or the agent          memex (local)              Later sessions
      │                        │                           │
      │  remember("prefers Go")│                           │
      │ ──────────────────────►│  saved to SQLite          │
      │                        │                           │
      │                        │  recall("testing prefs")  │
      │                        │ ◄─────────────────────────│
      │                        │ ─────────────────────────►│ relevant facts

1. Save — remember stores a short fact (deduplicated per user)
2. Find — recall or retrieve_context searches when the agent needs context
3. Update — update_memory revises a fact; old versions stay in the audit trail

Data never leaves your machine unless you copy the database file.

---

What you get

Feature	What it means for you
Local storage	SQLite file under ~/.memex — you own it
Smart search	Keyword search built in; optional MEMEX_HYBRID=1 for paraphrase-friendly matching
Context limits	retrieve_context returns only what fits your token budget
Safe updates	Revising a fact keeps history; nothing is silently overwritten
Agent + user facts	Track who said what (source: user / agent / system)
Multi-project scoping	Separate by user, agent, session, or metadata tags
Built-in guidance	MCP prompts teach agents when and how to use memory
Health check	memex doctor shows path, counts, and config

---

Documentation

Doc	For
Getting started	First-time setup in Cursor
For AI agents	When agents should read/write memory
Examples	MCP configs and scoping recipes
All docs	Index

Agents: fetch MCP prompts memory_guide, session_start, and remember_fact from the connected server.

---

Tools (10)

Everyday use — you usually only need the first three:

Tool	Plain English
remember	Save a fact
retrieve_context	Find relevant facts, sized for the model context window
recall	Search by keywords (query required)
list_memories	Browse stored facts without searching
update_memory	Change an existing fact (keeps history)
get_memory	Look up one fact by ID
forget	Remove one fact (soft delete)
delete_memories	Remove several facts
delete_all_memories	Wipe a user's memories (confirm=true)
memory_history	See how a fact changed over time

---

Settings

Variable	Purpose
MEMEX_DIR	Where to store data (default ~/.memex)
MEMEX_USER_ID	Your memory namespace (default default)
MEMEX_AGENT_ID	Separate memories per agent
MEMEX_RUN_ID	Tag memories to a session or run
MEMEX_HYBRID=1	Turn on extra local matching for paraphrases
MEMEX_VERBOSE=1	Log database path while debugging

---

Why memex?

Hosted 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.

	memex	Typical hosted memory
Setup	go install + MCP config	API keys, SDK, often Docker
Data	Your disk	Vendor cloud
Offline	Yes	Usually no
Cost	Free (local compute only)	Usage-based

---

Development

git clone https://github.com/kioie/memex.git && cd memex
make test              # fast unit tests
make test-integration  # MCP stdio roundtrip
memex doctor

See CONTRIBUTING.md · CHANGELOG.md · SECURITY.md

---

License

MIT — see LICENSE.