The knowledge layer your AI agents are missing.
Ingest anything. Remember everything. Retrieve what matters.
Documentation β’ Quick Start β’ Claude Code Plugin β’ FAQ
Important
Memex is in beta. It is functional and actively used, but expect rough edges, breaking changes between versions, and incomplete documentation. Feedback and bug reports are welcome β run memex report-bug or open an issue.
Memex exists because organizing knowledge shouldn't be your job. It is a self-organizing, self-reflecting knowledge system: you feed it raw material β articles, meeting notes, documents, web pages β and it extracts the facts, builds the connections, flags the contradictions, and synthesizes what it all means. When you need something, you ask, and the knowledge is already structured, cross-referenced, and ready. No filing. No tagging. No maintenance. Your knowledge compounds on its own so you can focus on the work that actually matters.
Memex is deliberately not an agent. It provides the storage, extraction, and retrieval β your agent of choice provides the synthesis and the judgment to call the right tool at the right moment. This separation of concerns means Memex works with any LLM agent that speaks MCP or REST, rather than locking you into a single interface. Conceptually, Memex overlaps with Andrej Karpathy's LLM Wiki.
Requirements Β· Features Β· Quick Start Β· Claude Code Plugin Β· See it in action Β· Documentation Β· Releasing Β· FAQ
- Python 3.12+ (3.13 tested in CI)
- uv >= 0.10.0
- PostgreSQL with pgvector
|
π₯ Ingest Anything |
π§ Five-Strategy Retrieval (TEMPR) |
π³ Hierarchical Page Index |
|
π Incremental Extraction |
βοΈ Contradiction Detection |
πͺ Reflection & Mental Models |
|
π¦ Vaults |
βοΈ Cloud-Native Storage & Assets |
π€ AI Agent Integration |
|
π REST API & Webhooks |
𧬠Lineage & Provenance |
π¦ Firefox Extension |
|
π Folder Sync |
π¦βπ₯ Pluggable Inference Backends |
π OpenTelemetry Observability |
|
π KV Store |
π§© Claude Code Plugin |
π Audit Logging |
|
βοΈ Memory Worth & Curation |
π§Ή Maintenance Linter |
π¬ Operator Diagnostics |
|
π§ Procedural Memory (Cases) |
Feature details
Feed Memex from any source β plain text, Markdown, PDFs, Word docs, PowerPoint, Excel, Outlook emails, web pages, or entire directories. File conversion is handled automatically via MarkItDown and PyMuPDF. Background and batch ingestion modes let you import large document collections without blocking. Pluggable note templates (built-in, global, and project-local .toml files) provide consistent structure for different note types.
memex note add "Quick inline note"
memex note add --file ./research-papers/ # directory of PDFs
memex note add --url https://example.com/article
memex note add --file report.md --asset diagram.png --backgroundA Firefox extension for one-click capture of articles, PDFs, and web pages directly into your Memex vaults. Content is extracted client-side via Mozilla Readability and converted to Markdown β bypassing bot detection and paywalled content that server-side scraping can't reach. API keys are encrypted at rest with AES-GCM.
Every search runs five independent retrieval strategies in parallel and fuses them with Reciprocal Rank Fusion β no single strategy has to be "right":
| Strategy | What it finds |
|---|---|
| Semantic | Conceptually similar facts via pgvector cosine distance |
| Keyword | Exact term matches via PostgreSQL full-text search |
| Graph | Entity-linked facts via NER, phonetic matching, and co-occurrence traversal |
| Temporal | Recent facts via exponential time-decay scoring |
| Mental Model | High-level synthesized insights from the reflection engine |
Post-fusion, MMR diversity filtering prunes near-duplicates using a hybrid cosine + entity Jaccard kernel. Optional after/before date bounds and tags filters let you scope any search.
Long documents are split into a structured table of contents with section-level summaries, token estimates, and unique node IDs. Read a 50-page PDF section by section instead of dumping the entire document into context. The page index powers skeleton-tree reasoning (--reason) and targeted answer synthesis (--summarize).
When you update a note (via note_key), Memex diffs the content against the previous version and only re-extracts changed blocks. Unchanged facts, entities, and embeddings are preserved β saving LLM calls and keeping ingestion fast for living documents.
New facts get scored against the existing graph as they ingest. Typed MemoryLink rows β contradicts, weakens, reinforces, and the causal types β feed into the FSFM composite that the maintenance linter runs over each vault. When graph pressure escalates a finding, a second LLM lint pass reads both contradicting units (along with their source dates, credibility, and authority) and proposes a winner with a confidence score. Approve via memex lint apply; reverse with memex lint reverse if the verdict turns out wrong. Search results include inline related_notes (notes sharing entities) and typed links (contradicts, reinforces, temporal, causes) for relationship discovery without additional queries.
A background 7-phase reflection loop (P0βP6) periodically reviews entities with new evidence, synthesizes observations, and builds versioned mental models. Trends between versions surface as stable patterns. Over time, Memex evolves from a collection of raw facts into structured understanding β "The team consistently prioritizes performance over feature velocity" emerges from dozens of individual meeting notes.
Isolate knowledge by project, team, or topic. Each vault is a self-contained scope for notes, memories, entities, and mental models. Policy-based access control (reader/writer/admin) with vault-scoped API keys lets you grant fine-grained permissions. Use read_vault_ids for cross-vault read access without write permissions.
Each vault includes an auto-generated natural language summary describing topics, themes, and statistics. Summaries regenerate automatically via a 3-tier strategy (on ingestion after cooldown, periodic background refresh, and on-demand via CLI or API). Use memex vault summary to view or regenerate a vault's summary.
The file store uses fsspec for backend-agnostic storage. Swap between local disk, Amazon S3, and Google Cloud Storage with a config change. File assets (images, PDFs, audio) are stored alongside notes and served through MCP as native content types (Image, Audio, File). The CLI and MCP tools support listing, retrieving, adding, and deleting assets per note.
server:
file_store:
type: s3 # or 'gcs', 'local'
root: my-bucket/memexFirst-class support for Claude Code, Claude Desktop, and any MCP-compatible client. Install the Claude Code plugin for one-step setup across all projects. ~55 MCP tools* with progressive disclosure (3-stage tool discovery by default) cover the full API surface. Search results include staleness flags (fresh/aging/stale/contested) and inline note relation links for relationship discovery. A slim Docker image (docker/mcp/Dockerfile) enables containerized MCP deployment with HTTP transport.
*The MCP surface is mid-refactor; the tool count moves a few up or down release-to-release. See MCP Tools reference for the current inventory.
A full FastAPI server with NDJSON streaming, OpenAPI docs, policy-based auth (reader/writer/admin) with vault-scoped API keys, rate limiting, and outgoing webhook subscriptions for event-driven integrations (ingestion.completed, reflection.completed).
Trace any mental model back through observations to the original source document. Full bidirectional provenance traversal (upstream, downstream, both) with configurable depth and child limits.
Sync a folder of Markdown notes (and PDFs, Word docs, Excel, PowerPoint, Outlook emails, and more) to Memex with memex note sync. Incremental sync tracks state locally β only changed files are re-processed. Deleted files are archived by default (preserving data, excluding from retrieval). Background batch mode, continuous watch mode (event-driven or polling), and a layered TOML config (note-sync.toml) make it easy to keep an Obsidian vault or any notes folder in sync.
memex note sync init ~/notes # create default config
memex note sync run ~/notes # sync changed files
memex note sync watch ~/notes # continuous syncSwap the built-in ONNX embedding and reranking models for any LiteLLM-supported provider (OpenAI, Gemini, Cohere, Ollama, etc.) via config. An inverse-sigmoid logit transform on LiteLLM reranker scores preserves the retrieval engine's scoring semantics.
Distributed tracing via Arize Phoenix. Session IDs propagate across spans, DSPy LLM calls get operation names, and background reflection jobs are tracked across tracing sessions.
A lightweight namespaced key-value store for structured facts, preferences, and conventions. Keys use namespace prefixes (global:, user:, project:<id>:, app:<id>:) for scoping. Each entry gets an embedding for semantic search, enabling fuzzy lookup alongside exact key access. Ideal for storing agent preferences, project conventions, and user facts that persist across sessions.
Give Claude Code persistent memory across all projects with a single plugin install. The plugin bundles the Memex MCP server, /remember, /recall, and /learnings slash commands, and session lifecycle hooks with intelligent context injection. A token-budgeted session briefing (memex briefing) replaces raw data dumps with a curated knowledge index β KV facts, vault summary, top entities with trend indicators, and available vaults β all within a configurable 1000 or 2000 token budget. Data-driven pre-compact nudges reference actual session stats (write counts, edit spirals, commits), and a progressive session note persists context across compaction boundaries via note_key. No per-project configuration needed.
An append-only audit trail backed by the metastore. Every significant action (ingestion, deletion, status change, reflection) is logged with the actor, resource ID, action type, and session ID. Dispatch is non-blocking β audit writes happen in the background without impacting request latency.
Most memory in Memex is declarative β facts, events, and observations about what is true. Procedural memory is the other half: how your team does things. The deploy verb that means "staging" here, the way this repo wants its PRs, the fix that worked last time.
It rides on the same substrate as everything else. A case is a note β the exact same Markdown-note row, stored and extracted the same way β but with role='case' and a job: it records a worked episode (Trigger / Situation / Actions / Outcome + Lesson) instead of describing the world. Submitting one (memex case submit) files the note, then runs an assignment step that links it to an existing procedure or drafts a new one, and the case's outcome bumps that procedure's success/failure counters. Procedures β and the strategies that pick between them for a context β live on a dedicated plane, surface as compact index cards in the session briefing, and graduate from draft to published through the maintenance lint queue.
The one-line distinction: a note says what is true; a case says what you did and how it turned out. Same storage, different job β and the case is what teaches Memex the procedure. (This is distinct from the KV store, which holds a user's stated one-line preferences and conventions; the procedural plane holds recipes Memex distils from real worked episodes.)
Note
Features like AI-generated answers, fact extraction, and reflection require an LLM API key. By default, Memex uses Gemini and needs GEMINI_API_KEY set in your environment. See Set the default model for other model providers.
Download e.g. the Postgres app, or use docker for just the database: docker compose up -d postgres (see docker-compose.yaml in this repository).
Requires Python 3.12+ and uv (>= 0.10.0).
uv tool install --refresh "memex-cli[server] @ git+https://github.com/JasperHG90/memex.git@latest#subdirectory=packages/cli"It's easiest to just alias the uv tool command: alias memex="uv tool run --from memex-cli memex"
Sets up your local storage and configuration.
memex config initMemex requires a running API server for all operations.
# In a separate terminal
memex server start -dFeed it knowledge.
# Isolate notes with vaults
memex vault create notes --description "Notes about things"
# Inline note
memex note add -v notes "Memex provides long-term memory that evolves."
# Capture a webpage
# Goes to the 'global' vault
memex note add --url "https://docs.python.org/3/tutorial/"
# Point it to local files
# Supports: MD, PDF, docx, xlsx, outlook, pptx
memex note add --file /path/to/file.md --vault notesAsk questions.
memex memory search "How does Python handle memory management?"Give Claude Code persistent memory across all projects β no per-project setup needed.
# Add the Memex marketplace
claude plugin marketplace add JasperHG90/memex
# Install the plugin
claude plugin install memex@memexOr from inside Claude Code: /plugin marketplace add JasperHG90/memex then /plugin install memex@memex.
The plugin provides slash commands β /remember, /recall, /learnings, /ingest, /lint, /handoff, /continue, and more β token-budgeted session briefing, data-driven lifecycle hooks, and the Memex MCP server. See packages/claude-code-plugin for details.
To update the claude code plugin, first execute claude plugin marketplace update, then claude plugin update memex@memex to update the claude code plugin.
- By default, the claude code plugin uses the MCP server from tag
latest. To override this, you can specify a project-level memex MCP server in your project's.mcp.json. - To override individual memex settings (e.g. MEMEX_BASE_URL), add these to './claude/settings.json', e.g.
{
"env": {
"MEMEX_SERVER_URL": "http://host.docker.internal:8000"
}
}Search across your knowledge base with TEMPR multi-strategy retrieval.
Get synthesized answers from your memories using --answer.
Find relevant documents with LLM-powered relevance reasoning using --reason.
Browse and explore entities extracted from your knowledge base.
Monitor your Memex instance at a glance.
Capture web content directly into your knowledge base.
Comprehensive guides and references live in docs/. The tree follows DiΓ‘taxis β tutorial, how-to, reference, explanation.
- Getting started: Install, configure, ingest, and search from scratch.
- Build an agent: Wire a Python agent to Memex over REST or MCP.
- Claude Code integration: Walk through the plugin end-to-end.
- Which models work well: Pick embedding, reranking, and LLM providers.
- Memory Worth and deprioritization: See curation in action.
- Contradiction detection: Land a conflicting fact and watch the linter resolve it.
- Note search vs memory search: Pick the right retrieval mode.
- Entity search: Explore the entity graph by hand.
- Ingest data: CLI, API, folder sync, and batch modes.
- Retrieve data: Search, browse, and filter.
- Use the KV store: Namespaced preferences, project bindings, and conventions.
- Attach assets to notes: Images, PDFs, audio.
- Deprioritize units: Demote without deleting.
- Reconsolidate an entity: Re-run the 7-phase loop for a single entity.
- Submit cases and derive procedures: Turn a worked episode into a reusable procedure.
- Trace lineage: Walk from mental model back to source.
- Run diagnostics: Manifold, retrieval, lint backlog.
- Backup and export: Get your data out at any time.
- Configure note templates: Pluggable
.tomltemplates. - Organize with vaults: Isolate by project, team, or topic.
- Apply lint findings: Approve or reverse LLM-proposed winners.
- Configure the server: Default model, embedding and reranking models, API keys, low-resource setup, deployment.
- Integrate with Claude Code: Plugin install and overrides.
- Integrate with the Hermes plugin: Hermes Agent memory provider.
- Wire Prometheus and Arize Phoenix: Metrics and traces.
- Install the Firefox plugin: One-click web capture.
- CLI commands
- API routes: REST surface.
- MCP tools: ~55 tools across asset, note, search, entity, KV, vault, outcome, curation, lint, diagnostics, procedural.
- Configuration options
- Data model: The full database schema.
- Failure modes: What blocks, what degrades gracefully.
- Observability: Metrics catalog and span attributes.
- Evaluation results: Internal suites and agent-integration scenarios (external benchmarks run occasionally).
- Design principles: P1βP13.
- Session briefings: How briefings get composed across harnesses.
- Mental-model observations: The read-only projection contract.
- How Memex is evaluated: The internal eval framework.
- High-level architecture: Layers and package map.
- Memory types: Notes, memory units, KV entries, observations.
- Extraction: How raw text becomes structured memory.
- Retrieval: TEMPR, RRF, composition, MMR.
- Synthesis and reflection: The 7-phase loop.
- Feedback: Memory Worth, outcome counters, FSFM scoring.
- Note lifecycle: Active, superseded, archived, appended.
- Procedural memory plane: Cases, procedures, strategies β recipes distilled from worked episodes.
Found a bug? Run
memex report-bugto open a pre-filled GitHub issue.
Memex uses semver with unified versions across all Python packages. TypeScript packages are bumped alongside.
Look at the conventional commits since the last tag:
| Commit type | Bump | Example |
|---|---|---|
fix: |
patch (0.0.x) | fix(core): handle null embeddings |
feat: |
minor (0.x.0) | feat(core): add entity graph |
feat!: or BREAKING CHANGE: |
major (x.0.0) | feat!: change API response format |
# 1. Check what changed since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD
# 2. Bump all versions, commit, and tag
just release 0.1.0
# 3. Push (triggers the release workflow)
git push && git push --tagsThe release.yaml GitHub Action automatically builds all artifacts and creates a GitHub Release with auto-generated release notes.
Memex's evaluation centers on an internal suite that grows with the system, not on a published leaderboard. It runs two layers:
- Retrieval and extraction regression β hand-verified scenarios assert that a specific query returns the right facts and ranks the right units. Seven suites run in CI in seconds against a snapshot-cached vault.
- Agent integration β the same scenarios, answered by a real agent driving Memex's tool surface (Claude Code over MCP, Hermes over the plugin). This measures whether the agent picks the right tool, cites honestly, and routes each write to the right place. It is the layer under active expansion.
This is where the work goes. See How Memex is evaluated for the framework and packages/eval to run it.
Memex also carries tooling to score against published long-memory datasets β LoCoMo and LongMemEval. These run on demand, not on a cadence, so read any numbers as point-in-time snapshots rather than a tracked result. An early LoCoMo run (first conversation, 47 of 50 QA pairs after excluding 3 image-only questions; answering model Claude Opus 4 via Claude Code, judge Gemini 3 Flash, 0β1 graded scale):
| Category | Count | Mean Score |
|---|---|---|
| Single-Hop | 9 | 0.944 |
| Multi-Hop | 9 | 1.000 |
| Open Domain | 3 | 1.000 |
| Temporal | 15 | 1.000 |
| Non-adversarial | 36 | 0.986 |
| Adversarial (unweighted) | 11 | 0.773 |
Retrieval stayed cheap on that run β a median 4,609 tokens per question, about 4.5% of total token usage, with the rest being agent overhead. Full methodology, retrieval-efficiency analysis, and per-question detail live in the evaluation results reference.
Memex is built as a monorepo:
packages/core: The brain. Extraction, Retrieval (TEMPR), Reflection, services, FastAPI server.packages/cli: The interface. Typer CLI commands, includingmemex note syncfor folder-based note synchronization.packages/mcp: The bridge. FastMCP server for AI agent integration.packages/common: The foundation. Shared models, config, and exceptions.packages/eval: The eval harness. Internal regression and agent-integration suites, plus external-benchmark tooling (LoCoMo, LongMemEval).packages/claude-code-plugin: The plugin. Claude Code plugin for cross-project memory integration.packages/firefox-extension: The capture. Firefox extension for web content ingestion.
Memex builds on ideas and code from these projects:
- Hindsight β the Hindsight retention engine formed the basis for Memex's memory system (extraction, retrieval, and reflection).
- PageIndex β inspired the hierarchical page index used for structured note retrieval.
Apache 2.0. See NOTICES for third-party attributions.








