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-bugor 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
|
📥 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) |
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 --background
A 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/memex
First-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 sync
Swap 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_KEYset 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 init
Memex requires a running API server for all operations.
# In a separate terminal
memex server start -d
Feed 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 notes
Ask 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@memex
Or 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.
latest. To override this, you can specify a project-level memex MCP server in your project's .mcp.json.{
"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.
.toml templates.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 --tags
The 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:
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, including memex note sync for 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:
Apache 2.0. See NOTICES for third-party attributions.
Python
97.8%
TypeScript
1.0%
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-bugor 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
|
📥 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) |
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 --background
A 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/memex
First-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 sync
Swap 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_KEYset 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 init
Memex requires a running API server for all operations.
# In a separate terminal
memex server start -d
Feed 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 notes
Ask 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@memex
Or 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.
latest. To override this, you can specify a project-level memex MCP server in your project's .mcp.json.{
"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.
.toml templates.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 --tags
The 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:
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, including memex note sync for 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:
Apache 2.0. See NOTICES for third-party attributions.
Python
97.8%
TypeScript
1.0%