memex

A durable, local-first memory layer for AI coding agents.

The filesystem is the memory · the index is disposable · every session is provable.

Documentation · User guide · Specification · Harness adapters

Why

Agents that matter forget things that matter: your stack, your rules, your decisions from last Tuesday. Vector databases and cloud memory services solve this with infrastructure. Memex solves it with a filesystem:

• The filesystem is the memory. Every memory is a Markdown page under ~/.memex/docs/ — human-readable, git-able, editable by hand, portable forever. No blobs, no lock-in, no server.

• The index is disposable. SQLite FTS5 provides fast BM25 search, and it is never the source of truth: delete mem.db, run memex rebuild-index, everything comes back from the pages.

• Every session is provable. Captured transcripts link to episode nodes, so any memory traces back to the conversation that produced it.

Related MCP server: exomem

Agents forget to call tools — memex doesn't rely on them remembering

One contract, every harness:

memex install              # interactive: pick a harness
memex install claude        # or codex, pi, copilot, custom

Quickstart

# install (Python 3.12+)
uv tool install --path . memex

# store a memory — it's a plain Markdown page
memex write --type preference --title "Deploy on Fridays" \
    --body "The team deploys to production on Fridays only." --tags deploy

# recall it — BM25-ranked, snippet-highlighted
memex recall "deploy"

# read it, edit it by hand, commit it to git
cat ~/.memex/docs/preferences/deploy-on-fridays.md

from memex import Memex, WriteInput

memex = Memex()
memex.write(WriteInput(type="entity", title="Ruff linter", body="Fast linter."))
result = memex.recall("linter", top_k=3)
provenance = memex.get_provenance(result.hits[0].slug)
memex.close()

memex_write · memex_recall · memex_consolidate · memex_forget · memex_ingest_transcript · memex_provenance · memex_export · memex_import

claude mcp add memex -- memex serve-mcp

memex verify --since "$PR_CREATED" --require-recall --require-write

Always checks: every page parses, the index matches content hashes, every [[link]] resolves. With --since, enforces recall/write activity evidence. Exit 1 fails the build. Ready-made workflow: marketplace/copilot/memex-verify.yml.

Commands

Documentation

Contributing

uv sync --all-groups
uv run pytest && uv run ruff check . && uv run mypy src tests

Contributions welcome — see AGENTS.md for engineering conventions and the guide for architecture context.

License

MIT © Memex contributors

Memex stores memory as plain files on your machine and treats stored memories and tool inputs as untrusted: logs never contain memory contents, archives are validated before extraction, and tool errors are sanitized.