How Memora Gives Claude Code Assistants Long-Term Memory and a Knowledge Graph

Anyone who has tried assigning long tasks to agents like Claude Code or Codex CLI knows this feeling. Yesterday you spent half a day tracking down a non-obvious authorization bug, discussed architectural constraints, and outlined a refactoring plan. Today you open a new session, and the model suggests that exact solution you rejected yesterday.

Regular text memory files like MEMORY.md grow unwieldy within a couple of weeks. Context gets clogged with duplicates, contradictory facts, and outdated plans. The Memora project solves this through the Model Context Protocol (MCP), transforming scattered agent notes into a structured knowledge graph.

What's Under the Hood and Why It Matters

Memora works as a Python MCP server, storing data in a local SQLite database or cloud storage (Cloudflare D1, S3, R2). The key here is not just saving strings, but how the system processes new facts.

When an agent completes a task and wants to save context, it calls the data absorption command (absorb). A built-in language model matches the fresh fact against existing records and classifies it: duplicate, update, contradiction, connection, or fundamentally new knowledge.

If the information updates an old entry, Memora builds a version chain. The old record isn't deleted without a trace—it gets marked as outdated, preserving the change history. During normal searches, the agent sees only the current snapshot, but can retrieve the full retrospective if needed.

What Sets This Project Apart in Practice

The repository brings together several engineering solutions that standard RAG memory for agents is severely lacking.

1. Smart Deduplication and Thematic Summaries

Instead of feeding the model dozens of similar text chunks, the tool consolidates facts by topic. The memory_digest(topic) method gathers all relevant memories, open TODOs, discovered bugs, and their connections in a single call.

Duplicates are tracked automatically:

# Поиск похожих записей через векторную близость и LLM-анализ
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Объединение записей с нужной стратегией
memory_merge(source_id=123, target_id=456, merge_strategy="append")

When comparing, the LLM gives a clear verdict: duplicate, similar thought, or different things—supplementing the assessment with reasoning and a recommendation.

2. Structured Documents and Atomic Fragments

Often an agent needs to remember not a short phrase, but an entire research report or architectural decision (ADR). If you save markdown as a single chunk, granular semantic search across it will perform poorly.

Memora parses markdown into a fragment tree:

• tables become separate claims;
• numbered lists become plan items;
• reference lists become references;
• risk sections are parsed as risks.

Each fragment is available for vector search independently, and the original document can be retrieved in full at any time. Fragments are protected from accidental deletion or merging by system checks.

3. Interactive Graph and Web Panel

Alongside the MCP server, a local web interface starts on port 8765. You can view the knowledge graph, filter connections by tags, track action timelines, and chat with the database through a built-in RAG chat.

The web interface chat supports function calls. You can ask the model directly from the browser: "Delete note #42" or "Update requirements in task #10", and it will make changes to the database.

Setup and Embedding Pitfalls

Install the package via pip:

pip install memora-mcp

For local embeddings without calling external APIs, the [local] option comes in handy:

pip install "memora-mcp[local]"

Connection to Claude Code is configured in the .mcp.json file at the project root:

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

The project authors honestly warn about one common configuration mistake. Memora can separate the provider for LLM (e.g., OpenRouter) and the provider for vector representations (e.g., Cloudflare Workers AI or OpenAI).

If you use OpenRouter for reasoning, remember: it has no embeddings endpoint. If you make a mistake in the config and don't set the MEMORA_EMBEDDING_STRICT=1 flag, the server silently falls back to primitive TF-IDF keyword search. The database will keep responding, but vector search quality will drop unnoticeably. Strict mode will immediately throw an error if the vectorization endpoint is unavailable.

For Neovim users, there's a nice bonus in the form of Telescope integration: the memora.lua plugin lets you search memory with a hotkey right while editing code.

Who This Project Is For

Memora is a good fit for those who actively use Claude Code, Codex CLI, or custom MCP-based agents for long-lived projects. It addresses the main pain point of agentic development—loss of context between session restarts.

If you need a knowledge base that doesn't get cluttered with duplicates and clearly visualizes connections between tasks and architectural decisions, trying the tool definitely makes sense. The source code is available under the MIT license in the agentic-box/memora repository.