Memex
Memex
Accountable memory that doesn't rot.
Your AI agent's memory is a git repo it can reason about. Every fact records who wrote it and why. When a new note contradicts an old one, the agent is told on the spot and you get an inbox to settle it. Nothing is overwritten; the history is the audit trail.


Memex is a git-backed markdown knowledge base that any MCP host (Claude Desktop, Cursor, your own agent) can read and write. Your notes are plain .md files you own, not rows in someone's database. How it works, in one page: ARCHITECTURE.md.
Status: pre-release, in active development. Brain, Graph and Conflicts (v0.1 to v0.3) are feature-complete: seven MCP tools, contradiction warnings, a browse UI, a force-directed graph and a conflicts inbox. Not yet tagged. See the roadmap.
Why it doesn't rot
Most "agent memory" is a bucket of embeddings that silently rots: stale facts linger, contradictions pile up, and you can never ask why the agent believes something. Memex is built on one engine, git:
Pillar | What it means | Powered by |
Provenance | Every note records which agent and session wrote it, when, and why. One write is exactly one commit. | frontmatter + git commits |
Contradiction detection | A write that collides with an existing note on the same | deterministic checks |
Time-travel | Ask what the brain knew on date X, and diff any two points. (UI planned, v0.4; the history is already in git.) | git history |
The detector is tuned to under-flag, because a tool that cries wolf is dead by lunchtime. Its correctness suite is mostly cases that assert nothing flags (restatements, explicit supersedes, unrelated notes with similar wording). It is the seed of an evals story, not one yet.
Related MCP server: auxly-memory-cli
Quickstart (about 60 seconds)
Needs Node 20+ and git.
git clone https://github.com/ronmasuary/Memex.git && cd Memex
npm run setup # installs + builds server, CLI (dist/) and UI (web/dist/)
npm link # optional: puts the `memex` command on your PATH
memex init ~/memex-vault # creates a git repo with a seed note
memex serve --vault ~/memex-vault # http://127.0.0.1:4321No npm link? Run the same commands as node dist/cli.js init … / node dist/cli.js serve ….
Keep the vault out of Dropbox, iCloud and OneDrive (cloud sync plus git corrupts .git). memex find <query> searches from the terminal.
Each vault is its own git repo. memex init stamps a committer identity onto it (your git config by default, or --name "Ada Lovelace" --email ada@example.com) and prints it, so the initial commit is signed by a real author rather than inheriting a stale global default.
Connect an MCP host
Desktop hosts can't resolve npx or a PATH bin, so the config needs absolute paths to node and dist/mcp.js. Instead of hand-writing them (and escaping backslashes on Windows), let Memex print the exact block with paths already resolved:
memex mcp-config --vault ~/memex-vault # Claude Desktop (default)
memex mcp-config --vault ~/memex-vault --host cursor # CursorIt prints a ready-to-paste mcpServers block and tells you which file to merge it into for your OS. Merge it, then fully restart the host. For reference, the block looks like this (your paths will be absolute and OS-correct):
{
"mcpServers": {
"memex": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/Memex/dist/mcp.js"],
"env": { "MEMEX_VAULT": "/absolute/path/to/memex-vault" }
}
}
}Config file locations: Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows); Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).
Hosts don't call memory tools unprompted. Paste the short block from MEMEX.md into your CLAUDE.md or Cursor rules so the agent actually uses them.
MCP tools
Tool | Purpose |
| Create or update a note, one git commit, returns contradiction warnings |
| Ranked search: title, id, 200-char snippet, max 8 hits |
| Full body of one note, capped by |
| Notes that link to a given note |
| Browse by project or tag |
| Tags with counts |
| Settle a contradiction: keep A, keep B, or keep both with a note. One commit; nothing deleted. Agents should use it only when you've decided |
Every tool caps its output so a memory lookup never floods the host's context.
The web UI
memex serve is a browser for the vault (read-only, with one exception: resolving a conflict, which is loopback-gated): notes grouped by project, rendered markdown with clickable [[wikilinks]], a backlinks panel, a provenance badge, and a force-directed graph of notes and links (/graph). In the graph, color is the project, size is backlink count, hover shows the title, click opens the note, and the project and tag filters re-lay-out what is left. The Conflicts tab lists every unresolved contradiction side by side, with each note's differing values and provenance, and the resolve actions. It follows your system light/dark setting.
How it works
Source of truth: markdown + YAML frontmatter, one note per file (
<project>/<slug>.md), in a git repo separate from this one.Index: a rebuildable, gitignored MiniSearch projection, refreshed by an mtime sweep. No native dependencies. Postgres + pgvector can slot in later behind the same interface.
Multi-machine: the vault is a git remote; clone it on your Mac and your Windows box.
Stack: TypeScript (Node 20, ESM),
@modelcontextprotocol/sdk,node:http(no framework), React + Vite + Tailwind,d3-forcewith hand-written SVG. CI on ubuntu, macOS and Windows. Decisions are recorded in docs/adr; the whole design is in ARCHITECTURE.md.
Roadmap
v0.1 — Brain. Markdown store, MCP read/write/search, contradiction warnings. (built, not yet tagged)
v0.2 — Graph. Wikilinks, backlinks, browse UI and the force-directed graph. (built, not yet tagged)
v0.3 — Conflicts. The contradiction inbox and resolve actions. (built, not yet tagged)
v0.4 — Time-travel. Scrub the brain's history; diff any two points.
v0.5 — Recall. Embeddings and hybrid semantic search on Postgres + pgvector (Docker lands here).
v0.6 — Obsidian sync. Point Memex at a real Obsidian vault, two-way.
Later: team and shared memory, a LangGraph memory adapter.
Contributing
Issues and ideas welcome; see CONTRIBUTING.md. Licensed MIT © Ron Masuary.
Available Tools
7 toolsget_backlinksA
List the notes that link to the given note id via [[wikilinks]].
Inputs: id (required).
list_notesB
List notes (id, title, project, tags), optionally filtered by project and/or tag.
Inputs: tag, limit, project.
list_tagsB
List tags with note counts, optionally within one project.
Inputs: project.
read_noteC
Read one note's full body by id.
Inputs: id (required), maxChars.
recallA
Search memory. Returns up to 8 ranked hits as title, id and a short snippet. Use read_note for the full text.
Inputs: query (required), limit, project.
rememberA
Save or update a note in the user's persistent memory. Re-using a title updates that note. Pass a stable key for a fact that should have one current value (e.g. 'storage-choice'); if a different active note already holds a different value for that key, the result warns you. If the project already uses a different-but-similar key, the result nudges you to reuse it. To replace an older note on purpose, add a line 'Supersedes: [[old-id]]' to the body.
Inputs: body (required), title (required), key, why, +2 more.
resolve_conflictA
Resolve a contradiction between two notes (ids from a remember WARNING, or the Conflicts page). Only do this when the user has told you which side is right; if unsure, ask them. a is the older note, b the newer. Actions: keep_a (b is marked superseded), keep_b (a is marked superseded), or keep_both (requires note, a reconciliation explaining how both hold; both stay active). Each resolution is exactly one git commit. Nothing is deleted.
Inputs: a (required), b (required), action (required), why, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct role: read_note (fetch full body by id) vs recall (ranked snippet search), list_notes vs list_tags (different resources), and remember (write/update) vs resolve_conflict (deliberate contradiction workflow). The descriptions explicitly cross-reference each other (recall says 'use read_note for the full text'; remember's warnings feed resolve_conflict), so an agent can pick correctly.
Four tools follow a verb_noun pattern (read_note, get_backlinks, list_notes, list_tags) and all names are uniformly snake_case. The three memory-lifecycle tools use bare verbs (remember, recall, resolve_conflict), which is a minor but readable deviation rather than inconsistency.
Seven tools is well-scoped for a personal notes/memory server, and each earns its place: read, write, search, list, list tags, backlinks, and conflict resolution. No redundant or filler tools are present.
The surface covers the full read/write/search/update lifecycle plus backlinks and explicit conflict resolution, with supersede semantics substituting for deletion. Minor gaps remain: there is no 'forget'/delete operation at all, and no way to list a note's outgoing links (only backlinks), which agents may want for graph navigation.
Maintenance
Related MCP Connectors
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
One memory for every AI you work with: your rules, notes and decisions in your own Git repo.
Provenance-carrying memory for AI agents: corrections supersede, never overwrite. Free, API + MCP.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceOpen, Git-native memory protocol for MCP agents: stores memories as Markdown files in a Git repo, enabling portability, auditability, and human-editable memory across different AI agents.103 npm15MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first, file-based memory layer for AI agents — one shared Markdown vault across Claude, Codex, Gemini, Cursor and any MCP client. Provides read/write memory tools with an audit trail, per-agent trust levels, and Git sync; no cloud and no lock-in.2MIT
- AlicenseAqualityBmaintenanceGit-native long-term memory for AI agents: your markdown files are the source of truth, the search index is a disposable projection rebuilt from git, and every memory the agent writes is a reviewable git commit. Served over one OAuth-secured MCP endpoint with hybrid lexical+semantic recall and a gated, git-first commit_note write tool.78AGPL 3.0
- AlicenseAqualityAmaintenanceAudit-grade, git-versioned memory for AI coding agents that enables saving, searching, editing, and rolling back facts through markdown files served via MCP.39358 PyPI46MIT