memora

<h1 align="center"><img src="media/memora_new.gif" width="60" alt="Memora Logo" align="absmiddle"> Memora</h1> <p align="center">_{_{<i>"You never truly know the value of a moment until it becomes a memory."</i>}}</p> <p align="center"> <b>Give your AI agents persistent collective memory</b><br> An MCP memory layer for agents: structured storage, semantic retrieval, graph relations, and source-backed cross-session context. </p> <p align="center"> <a href="https://github.com/agentic-box/memora/releases"><img src="https://img.shields.io/github/v/tag/agentic-box/memora?label=version&color=blue" alt="Version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a> <a href="https://github.com/thedotmack/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code"></a> </p> <p align="center"> <img src="media/memora-absorb-digest-flow.gif" alt="Memora absorb and digest flow" width="820"> </p> <p align="center"> <b>Absorb agent work into durable graph memory, then use <code>memory_digest(topic)</code> to retrieve relevant memories, TODOs/issues, related edges, and source IDs.</b> </p> <p align="center"> <b><a href="#features">Features</a></b> · <b><a href="#preview">Preview</a></b> · <b><a href="#install">Install</a></b> · <b><a href="#usage">Usage</a></b> · <b><a href="#configuration">Config</a></b> · <b><a href="#multi-database-routing">Multi-DB</a></b> · <b><a href="#container-deployment">Containers</a></b> · <b><a href="#live-graph-server">Live Graph</a></b> · <b><a href="#cloud-graph">Cloud Graph</a></b> · <b><a href="#chat-with-memories">Chat</a></b> · <b><a href="#semantic-search--embeddings">Semantic Search</a></b> · <b><a href="#document-storage">Documents</a></b> · <b><a href="#llm-deduplication">LLM Dedup</a></b> · <b><a href="#memory-linking">Linking</a></b> · <b><a href="#neovim-integration">Neovim</a></b> </p>

Features

Core Storage

• 💾 Persistent Storage - SQLite with optional cloud sync (S3, R2, D1)
• 🗄️ Multi-database routing - One process serves many stores; a workspace reaches its own at /mcp/<name> (see Multi-database routing)
• 📂 Hierarchical Organization - Section/subsection structure with auto-hierarchy assignment
• 📦 Export/Import - Backup and restore with merge strategies

Absorb & Lineage

• 🧬 Absorb - Feed facts in; an LLM classifies each against the store (duplicate / update / contradiction / related / new), skips duplicates, links relations, and consolidates related facts — with dry_run preview
• 🌱 Supersession Lineage - Updates supersede old knowledge instead of deleting it; retrieval follows the chain to the current version by default (follow modes: active, latest, full_history)
• 🗞️ Topic Digest - memory_digest(topic) bundles relevant memories, open TODOs/issues, related edges, and source IDs into one retrieval

Search & Intelligence

• 🔍 Semantic Search - Vector embeddings (TF-IDF, sentence-transformers, OpenAI)
• 🎯 Advanced Queries - Full-text, date ranges, tag filters (AND/OR/NOT), hybrid search
• 🔀 Cross-references - Auto-linked related memories based on similarity
• 🤖 LLM Deduplication - Find and merge duplicates with AI-powered comparison
• 🔗 Memory Linking - Typed edges, importance boosting, and cluster detection

Document Storage

• 📄 Structured Documents - Store markdown documents as searchable fragment trees (claims, plan items, references, risks)
• 🔒 Fragment Integrity - Guards against accidental delete/merge/absorb of document fragments
• 🔍 Granular Search - Individual claims and findings are semantically searchable while the full document remains retrievable as a unit

Tools & Visualization

• ⚡ Memory Automation - Structured tools for TODOs, issues, and sections
• 🕸️ Knowledge Graph - Interactive visualization with Mermaid rendering and cluster overlays
• 🌐 Live Graph Server - Built-in HTTP server with cloud-hosted option (D1/Pages)
• 💬 Chat with Memories - RAG-powered chat panel with LLM tool calling to search, create, update, and delete memories via streaming chat
• 📡 Event Notifications - Poll-based system for inter-agent communication
• 📊 Statistics & Analytics - Tag usage, trends, and connection insights
• 🧠 Memory Insights - Activity summary, stale detection, consolidation suggestions, and LLM-powered pattern analysis
• 📜 Action History - Track all memory operations (create, update, delete, merge, boost, link) with grouped timeline view

Preview

<p align="center"> <img src="media/demo.gif" alt="Memora memory graph demo" width="320"> <img src="media/demo2.gif" alt="Memora memory interaction demo" width="320"> </p>

Install

Two paths. pip is a local stdio child the client spawns. A container is a detached HTTP service you start with up; with MEMORA_DATABASES it serves multiple stores from one process. The LaunchAgent supervises the proxy, not the container — after a host restart the listener can come back while its upstream is still stopped. If you are running memora as a service, the container path is the install.

pip (local / stdio)

pip install memora-mcp

The PyPI package is memora-mcp (bare memora on PyPI is an unrelated project). Includes cloud storage (S3/R2) and OpenAI embeddings out of the box.

# Optional: local embeddings (offline, ~2GB for PyTorch)
pip install "memora-mcp[local]"

# Latest development version straight from git
pip install "git+https://github.com/agentic-box/memora.git"

Then spawn it from .mcp.json with "command": "memora-server" (see Configuration).

Container (HTTP service)

Default runtime is Apple's container CLI. Every container operation scripts/memora-instance.sh performs (build, up, status, logs, down) uses $MEMORA_CONTAINER_BIN (default container). The generated proxy process does not; it hardcodes container list.

Before the first build:

1. Install Apple's container CLI (signed pkg from its GitHub releases). It needs a Mac with Apple silicon running macOS 26 — Apple does not support older macOS versions for container.

2. Start the runtime — Apple's documented first command, which also installs a kernel if none is configured:

   container system start
   

3. Clone this repo and cd into it:

   git clone https://github.com/agentic-box/memora.git
   cd memora
   

4. Copy the instance template. It ships with INSTANCE=myinstance so the later build/up/proxy lines match without renaming. Edit PORT and a backend (STORAGE_URI, VOLUME, or MEMORA_DATABASES):

   cp instances/example.env instances/myinstance.env
   

5. Create the credential file and install the proxy the LaunchAgent will run. cred_args() requires a .mcp.json whose mcpServers.memora.env holds CLOUDFLARE_API_TOKEN (D1 access) and the embedding/LLM keys — up dies if that file is missing. The script looks for ~/.config/memora/credentials.mcp.json if that file exists, otherwise ~/repos/agentic-box/.mcp.json. Set CRED_SOURCE in the instance file to pick a path. Separately, proxy renders a plist whose executable is $MEMORA_PROXY_BIN (default ~/.local/libexec/memora/memora_proxy.py) and whose logs live in $MEMORA_LOG_DIR (default ~/.local/var/log) — nothing creates either on a fresh clone.

   mkdir -p ~/.config/memora ~/.local/libexec/memora ~/.local/var/log
   cp scripts/memora_proxy.py ~/.local/libexec/memora/
   # real values; any key is fine, an absent file is not
   # the default umask is permissive -- chmod 600 keeps other local accounts out
   cat > ~/.config/memora/credentials.mcp.json <<'JSON'
   {"mcpServers":{"memora":{"env":{"CLOUDFLARE_API_TOKEN":"REPLACE","OPENAI_API_KEY":"REPLACE"}}}}
   JSON
   chmod 600 ~/.config/memora/credentials.mcp.json
   

   That JSON is the minimal correct config: both the LLM and embeddings use the default OpenAI host with a real OpenAI key. Do not add OPENAI_BASE_URL pointing at OpenRouter without the embedding pair from Embeddings — OpenRouter has no embeddings endpoint, every embed call 404s, and memora silently falls back to TF-IDF keyword bags while looking healthy.

Then:

./scripts/memora-instance.sh build myinstance   # tags IMAGE from myinstance.env (memora-pilot if IMAGE is unset)
./scripts/memora-instance.sh up      myinstance # runs that same IMAGE
./scripts/memora-instance.sh proxy   myinstance # render the LaunchAgent; run the printed launchctl

up does not publish a host port. The listener the workspace connects to is the proxy. proxy only renders a macOS LaunchAgent and prints the launchctl commands — it does not load the service. Run those printed commands.

The printed workspace URL is always http://127.0.0.1:<PORT>/mcp (the registry default). For a non-default store, append /<name> yourself — a bare /mcp on a registry silently binds MEMORA_DEFAULT_DB:

{"mcpServers": {"memora": {"type": "http", "url": "http://127.0.0.1:<PORT>/mcp/<store>"}}}

Proxy rationale, credentials, instance files, and MEMORA_CONTAINER_BIN: Container Deployment.

<details id="usage"> <summary><big><big><strong>Usage</strong></big></big></summary>

The server runs automatically when configured in Claude Code. Manual invocation:

# Default (stdio mode for MCP)
memora-server

# With graph visualization server
memora-server --graph-port 8765

# HTTP transport (alternative to stdio)
memora-server --transport streamable-http --host 127.0.0.1 --port 8080

</details> <details id="configuration"> <summary><big><big><strong>Configuration</strong></big></big></summary>

Claude Code

Add to .mcp.json in your project root:

Local DB:

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

Cloud DB (Cloudflare D1) - Recommended:

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": ["--no-graph"],
      "env": {
        "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
        "CLOUDFLARE_API_TOKEN": "<your-api-token>",
        "MEMORA_ALLOW_ANY_TAG": "1"
      }
    }
  }
}

With D1, use --no-graph to disable the local visualization server. Instead, use the hosted graph at your Cloudflare Pages URL (see Cloud Graph).

Cloud DB (S3/R2) - Sync mode:

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "AWS_PROFILE": "memora",
        "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com",
        "MEMORA_STORAGE_URI": "s3://memories/memories.db",
        "MEMORA_CLOUD_ENCRYPT": "true",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.memora]
  command = "memora-server"  # or full path: /path/to/bin/memora-server
  args = ["--no-graph"]
  env = {
    AWS_PROFILE = "memora",
    AWS_ENDPOINT_URL = "https://<account-id>.r2.cloudflarestorage.com",
    MEMORA_STORAGE_URI = "s3://memories/memories.db",
    MEMORA_CLOUD_ENCRYPT = "true",
    MEMORA_ALLOW_ANY_TAG = "1",
  }

</details> <details id="environment-variables"> <summary><big><big><strong>Environment Variables</strong></big></big></summary>

| Variable | Description | |------------------------|--------------------------