JasperHG90/memex

A (personal) knowledge base for LLMs that turns notes into structured, searchable long-term memory.

17

stars

1,758

commits

Python

primary language

Aug 4, 2026

updated

agentic-ai
agent-memory
agents
postgres

README

Memex Logo

Memex

A Knowledge Base for LLMs

The knowledge layer your AI agents are missing.
Ingest anything. Remember everything. Retrieve what matters.

DocumentationQuick StartClaude Code PluginFAQ

Python Python 3.12+ Apache 2.0 v1.0.0-rc Tests

[!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.

Vision

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


Requirements

  1. Python 3.12+ (3.13 tested in CI)
  2. uv >= 0.10.0
  3. PostgreSQL with pgvector

Features

📥 Ingest Anything
Markdown, PDF, Word, PowerPoint, Excel, Outlook emails, web pages, or entire directories. Conversion via MarkItDown & PyMuPDF. Pluggable note templates, asset management, and batch CLI operations.

🧠 Five-Strategy Retrieval (TEMPR)
Semantic, Keyword, Graph, Temporal, and Mental Model — five strategies run in parallel, fused via Reciprocal Rank Fusion. MMR diversity filtering prunes near-duplicates.

🌳 Hierarchical Page Index
Documents are split into a structured TOC with section summaries, token estimates, and node IDs. Read a 50-page PDF section by section instead of dumping everything into context.

🔄 Incremental Extraction
Update a note and Memex diffs the content, only re-extracting changed blocks. Unchanged facts, entities, and embeddings are preserved — fast for living documents.

⚔️ Contradiction Detection
New facts get scored against the existing graph. The FSFM linter watches for graph pressure between contradicting units; when the signal escalates, an LLM lint pass proposes a winner you can apply or reverse with one command. Retrieval favors current information.

🪞 Reflection & Mental Models
A 7-phase background loop (P0–P6) synthesizes observations into versioned mental models per entity, tracks trends across versions, and surfaces stable patterns. Memex evolves from raw facts into structured understanding over time.

🏦 Vaults
Isolate knowledge by project, team, or topic. Policy-based ACL (reader/writer/admin) with vault-scoped API keys. Cross-vault read access for shared knowledge. Auto-generated vault summaries with 3-tier regeneration.

☁️ Cloud-Native Storage & Assets
Notes and file assets (images, PDFs, audio) stored via fsspec — swap between local disk, S3, and GCS with a config change. PostgreSQL + pgvector for metadata and vector search.

🤖 AI Agent Integration
First-class MCP support for Claude Code, Claude Desktop, and any MCP-compatible client. ~55 MCP tools* with progressive disclosure, staleness flags on search results, note relation links, survey-based query decomposition, stdio/HTTP/SSE transports, slim Docker image decoupled from core. *surface is mid-refactor; tool count moves a few up or down release-to-release.

🌐 REST API & Webhooks
FastAPI server with NDJSON streaming, OpenAPI docs, policy-based auth, vault-scoped API keys, rate limiting, and CORS extension support.

🧬 Lineage & Provenance
Trace any mental model back through observations to the original source document. Full bidirectional provenance traversal with depth control.

🦊 Firefox Extension
One-click save of articles, PDFs & web pages. Readability extraction, Markdown conversion, inline image capture. AES-GCM encrypted API key storage.

📂 Folder Sync
Sync Obsidian vaults or any local folder to Memex. Multi-format support, asset upload, frontmatter skip markers, SQLite state tracking, watchdog/polling watch modes, archive-on-delete.

🐦‍🔥 Pluggable Inference Backends
Swap built-in ONNX embedding & reranking models for any LiteLLM provider — OpenAI, Gemini, Cohere, Ollama. Inverse-sigmoid logit transform preserves retrieval scoring.

🔭 OpenTelemetry Observability
Distributed tracing with Arize Phoenix — session IDs on spans, operation names on DSPy LLM calls, background reflection jobs tracked across tracing sessions.

🔑 KV Store
Namespaced key-value store for structured facts, preferences, and conventions. Semantic search via embeddings, exact key lookup, namespace filtering (global, user, project, app).

🧩 Claude Code Plugin
One-step persistent memory across all projects. Token-budgeted session briefing, /remember, /recall, and /learnings skills, data-driven session hooks, progressive session notes, and Memex MCP server — bundled as a Claude Code plugin.

📋 Audit Logging
Append-only audit trail tracking actions, actors, resource IDs, and session IDs. Non-blocking background dispatch backed by the metastore.

⚖️ Memory Worth & Curation
Every memory unit carries a Memory Worth score that rises with useful outcomes and falls with unhelpful ones. An FSFM-inspired composite blends graph pressure, low MW, staleness, and entity dormancy to flag candidates for deprioritization — never deletion. Restore at any time.

🧹 Maintenance Linter
A periodic linter scans the vault for fact-state issues — composite candidates, high-MW units under graph pressure, low-credibility contradictions. Escalations get a pre-attached LLM-proposed winner you can apply or reverse with one command.

🔬 Operator Diagnostics
The `memex diagnostics` CLI inspects the embedding manifold, retrieval ranking signals, vault summary stats, and pending lint backlog. Pair with the OpenTelemetry traces and Prometheus metrics for a full operator view.

🧭 Procedural Memory (Cases)
Beyond facts — capture how your team does things. Submit a worked episode as a case (a note with a job) and Memex links it to a reusable procedure or drafts a new one; strategies pick a procedure for a context. Assignment-judged, draft-then-activate via the lint queue, with success/failure counters per procedure.

Feature details

Ingest anything

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

Firefox extension

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.

firefox

Five-strategy retrieval (TEMPR)

Every search runs five independent retrieval strategies in parallel and fuses them with Reciprocal Rank Fusion — no single strategy has to be "right":

StrategyWhat it finds
SemanticConceptually similar facts via pgvector cosine distance
KeywordExact term matches via PostgreSQL full-text search
GraphEntity-linked facts via NER, phonetic matching, and co-occurrence traversal
TemporalRecent facts via exponential time-decay scoring
Mental ModelHigh-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.

Hierarchical page index

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

Incremental extraction

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.

Contradiction detection and note relations

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.

Reflection and mental models

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.

Vaults

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.

Cloud-native storage and assets

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

AI agent integration

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.

REST API and webhooks

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

Lineage and provenance

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.

Folder sync

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

Pluggable inference backends

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.

OpenTelemetry observability

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.

KV store

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.

Claude Code plugin

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.

Audit logging

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.

Procedural memory (cases)

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

🚀 Quick Start

[!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.

1. Set up postgres

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

2. Install

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"

3. Initialize

Sets up your local storage and configuration.

memex config init

4. Start the Server

Memex requires a running API server for all operations.

# In a separate terminal
memex server start -d

5. Ingest

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?"

See it in action

Claude Code Plugin

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.

Updating the claude code plugin

To update the claude code plugin, first execute claude plugin marketplace update, then claude plugin update memex@memex to update the claude code plugin.

Overriding defaults

  • 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"
  }
}

Claude Code using Memex for long-term memory

Search across your knowledge base with TEMPR multi-strategy retrieval.

Memory search showing results for Python memory management

Memory Search with AI Answer

Get synthesized answers from your memories using --answer.

Memory search with AI-generated answer

Note Search with Reasoning

Find relevant documents with LLM-powered relevance reasoning using --reason.

Note search with reasoning annotations

Entity Explorer

Browse and explore entities extracted from your knowledge base.

Entity list and related entity exploration

System Stats

Monitor your Memex instance at a glance.

System statistics overview

URL Ingestion

Capture web content directly into your knowledge base.

Ingesting a URL into Memex

📚 Documentation

Comprehensive guides and references live in docs/. The tree follows Diátaxis — tutorial, how-to, reference, explanation.

Tutorials — learn by doing

How-to guides — get a job done

Reference — look it up

Explanation — understand the why

Found a bug? Run memex report-bug to open a pre-filled GitHub issue.

Releasing

Memex uses semver with unified versions across all Python packages. TypeScript packages are bumped alongside.

How to determine the version bump

Look at the conventional commits since the last tag:

Commit typeBumpExample
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

Release workflow

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

Evaluation

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.

External benchmarks (occasional)

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):

CategoryCountMean Score
Single-Hop90.944
Multi-Hop91.000
Open Domain31.000
Temporal151.000
Non-adversarial360.986
Adversarial (unweighted)110.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.

🏗️ Architecture

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.

Acknowledgements

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.

License

Apache 2.0. See NOTICES for third-party attributions.

Contributors

JasperHG90

1,714 commits

RicardoAGL

20 commits

claude

2 commits

JasperHG90/memex

A (personal) knowledge base for LLMs that turns notes into structured, searchable long-term memory.

17

stars

1,758

commits

Python

primary language

Aug 4, 2026

updated

agentic-ai
agent-memory
agents
postgres

README

Memex Logo

Memex

A Knowledge Base for LLMs

The knowledge layer your AI agents are missing.
Ingest anything. Remember everything. Retrieve what matters.

DocumentationQuick StartClaude Code PluginFAQ

Python Python 3.12+ Apache 2.0 v1.0.0-rc Tests

[!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.

Vision

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


Requirements

  1. Python 3.12+ (3.13 tested in CI)
  2. uv >= 0.10.0
  3. PostgreSQL with pgvector

Features

📥 Ingest Anything
Markdown, PDF, Word, PowerPoint, Excel, Outlook emails, web pages, or entire directories. Conversion via MarkItDown & PyMuPDF. Pluggable note templates, asset management, and batch CLI operations.

🧠 Five-Strategy Retrieval (TEMPR)
Semantic, Keyword, Graph, Temporal, and Mental Model — five strategies run in parallel, fused via Reciprocal Rank Fusion. MMR diversity filtering prunes near-duplicates.

🌳 Hierarchical Page Index
Documents are split into a structured TOC with section summaries, token estimates, and node IDs. Read a 50-page PDF section by section instead of dumping everything into context.

🔄 Incremental Extraction
Update a note and Memex diffs the content, only re-extracting changed blocks. Unchanged facts, entities, and embeddings are preserved — fast for living documents.

⚔️ Contradiction Detection
New facts get scored against the existing graph. The FSFM linter watches for graph pressure between contradicting units; when the signal escalates, an LLM lint pass proposes a winner you can apply or reverse with one command. Retrieval favors current information.

🪞 Reflection & Mental Models
A 7-phase background loop (P0–P6) synthesizes observations into versioned mental models per entity, tracks trends across versions, and surfaces stable patterns. Memex evolves from raw facts into structured understanding over time.

🏦 Vaults
Isolate knowledge by project, team, or topic. Policy-based ACL (reader/writer/admin) with vault-scoped API keys. Cross-vault read access for shared knowledge. Auto-generated vault summaries with 3-tier regeneration.

☁️ Cloud-Native Storage & Assets
Notes and file assets (images, PDFs, audio) stored via fsspec — swap between local disk, S3, and GCS with a config change. PostgreSQL + pgvector for metadata and vector search.

🤖 AI Agent Integration
First-class MCP support for Claude Code, Claude Desktop, and any MCP-compatible client. ~55 MCP tools* with progressive disclosure, staleness flags on search results, note relation links, survey-based query decomposition, stdio/HTTP/SSE transports, slim Docker image decoupled from core. *surface is mid-refactor; tool count moves a few up or down release-to-release.

🌐 REST API & Webhooks
FastAPI server with NDJSON streaming, OpenAPI docs, policy-based auth, vault-scoped API keys, rate limiting, and CORS extension support.

🧬 Lineage & Provenance
Trace any mental model back through observations to the original source document. Full bidirectional provenance traversal with depth control.

🦊 Firefox Extension
One-click save of articles, PDFs & web pages. Readability extraction, Markdown conversion, inline image capture. AES-GCM encrypted API key storage.

📂 Folder Sync
Sync Obsidian vaults or any local folder to Memex. Multi-format support, asset upload, frontmatter skip markers, SQLite state tracking, watchdog/polling watch modes, archive-on-delete.

🐦‍🔥 Pluggable Inference Backends
Swap built-in ONNX embedding & reranking models for any LiteLLM provider — OpenAI, Gemini, Cohere, Ollama. Inverse-sigmoid logit transform preserves retrieval scoring.

🔭 OpenTelemetry Observability
Distributed tracing with Arize Phoenix — session IDs on spans, operation names on DSPy LLM calls, background reflection jobs tracked across tracing sessions.

🔑 KV Store
Namespaced key-value store for structured facts, preferences, and conventions. Semantic search via embeddings, exact key lookup, namespace filtering (global, user, project, app).

🧩 Claude Code Plugin
One-step persistent memory across all projects. Token-budgeted session briefing, /remember, /recall, and /learnings skills, data-driven session hooks, progressive session notes, and Memex MCP server — bundled as a Claude Code plugin.

📋 Audit Logging
Append-only audit trail tracking actions, actors, resource IDs, and session IDs. Non-blocking background dispatch backed by the metastore.

⚖️ Memory Worth & Curation
Every memory unit carries a Memory Worth score that rises with useful outcomes and falls with unhelpful ones. An FSFM-inspired composite blends graph pressure, low MW, staleness, and entity dormancy to flag candidates for deprioritization — never deletion. Restore at any time.

🧹 Maintenance Linter
A periodic linter scans the vault for fact-state issues — composite candidates, high-MW units under graph pressure, low-credibility contradictions. Escalations get a pre-attached LLM-proposed winner you can apply or reverse with one command.

🔬 Operator Diagnostics
The `memex diagnostics` CLI inspects the embedding manifold, retrieval ranking signals, vault summary stats, and pending lint backlog. Pair with the OpenTelemetry traces and Prometheus metrics for a full operator view.

🧭 Procedural Memory (Cases)
Beyond facts — capture how your team does things. Submit a worked episode as a case (a note with a job) and Memex links it to a reusable procedure or drafts a new one; strategies pick a procedure for a context. Assignment-judged, draft-then-activate via the lint queue, with success/failure counters per procedure.

Feature details

Ingest anything

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

Firefox extension

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.

firefox

Five-strategy retrieval (TEMPR)

Every search runs five independent retrieval strategies in parallel and fuses them with Reciprocal Rank Fusion — no single strategy has to be "right":

StrategyWhat it finds
SemanticConceptually similar facts via pgvector cosine distance
KeywordExact term matches via PostgreSQL full-text search
GraphEntity-linked facts via NER, phonetic matching, and co-occurrence traversal
TemporalRecent facts via exponential time-decay scoring
Mental ModelHigh-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.

Hierarchical page index

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

Incremental extraction

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.

Contradiction detection and note relations

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.

Reflection and mental models

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.

Vaults

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.

Cloud-native storage and assets

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

AI agent integration

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.

REST API and webhooks

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

Lineage and provenance

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.

Folder sync

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

Pluggable inference backends

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.

OpenTelemetry observability

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.

KV store

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.

Claude Code plugin

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.

Audit logging

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.

Procedural memory (cases)

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

🚀 Quick Start

[!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.

1. Set up postgres

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

2. Install

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"

3. Initialize

Sets up your local storage and configuration.

memex config init

4. Start the Server

Memex requires a running API server for all operations.

# In a separate terminal
memex server start -d

5. Ingest

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?"

See it in action

Claude Code Plugin

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.

Updating the claude code plugin

To update the claude code plugin, first execute claude plugin marketplace update, then claude plugin update memex@memex to update the claude code plugin.

Overriding defaults

  • 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"
  }
}

Claude Code using Memex for long-term memory

Search across your knowledge base with TEMPR multi-strategy retrieval.

Memory search showing results for Python memory management

Memory Search with AI Answer

Get synthesized answers from your memories using --answer.

Memory search with AI-generated answer

Note Search with Reasoning

Find relevant documents with LLM-powered relevance reasoning using --reason.

Note search with reasoning annotations

Entity Explorer

Browse and explore entities extracted from your knowledge base.

Entity list and related entity exploration

System Stats

Monitor your Memex instance at a glance.

System statistics overview

URL Ingestion

Capture web content directly into your knowledge base.

Ingesting a URL into Memex

📚 Documentation

Comprehensive guides and references live in docs/. The tree follows Diátaxis — tutorial, how-to, reference, explanation.

Tutorials — learn by doing

How-to guides — get a job done

Reference — look it up

Explanation — understand the why

Found a bug? Run memex report-bug to open a pre-filled GitHub issue.

Releasing

Memex uses semver with unified versions across all Python packages. TypeScript packages are bumped alongside.

How to determine the version bump

Look at the conventional commits since the last tag:

Commit typeBumpExample
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

Release workflow

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

Evaluation

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.

External benchmarks (occasional)

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):

CategoryCountMean Score
Single-Hop90.944
Multi-Hop91.000
Open Domain31.000
Temporal151.000
Non-adversarial360.986
Adversarial (unweighted)110.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.

🏗️ Architecture

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.

Acknowledgements

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.

License

Apache 2.0. See NOTICES for third-party attributions.

Contributors

JasperHG90

1,714 commits

RicardoAGL

20 commits

claude

2 commits

Languages

Python

97.8%

TypeScript

1.0%