By default the local database sits at ~/.local/share/memora/memories.db. The package is called memora-mcp, the current version is 0.3.3, and it needs Python 3.10 or newer. The server publishes forty-three tools, from creating a memory to verifying the integrity of the store.

Installation and connecting agents

The README suggests installing straight from GitHub:

If you want local sentence-transformers:

The server can be started in three modes:

For Claude Code a minimal .mcp.json is enough:

There are four meaningful parts here. The command field makes Claude Code run Memora as a separate process. The MEMORA_DB_PATH variable determines which SQLite file keeps all the durable data. The MEMORA_ALLOW_ANY_TAG flag lets the agent use tags without a predefined allowlist. And MEMORA_GRAPH_PORT brings up the browser graph interface on the given port.

For Codex CLI the README shows a cloud-sync variant in ~/.codex/config.toml:

The meaning is the same: the agent gets one MCP server, and where memory physically lives is decided by Memora through environment variables.

The first write, and smarter absorption

The simplest operation is saving an already-formulated thought, and there is no reason to run such a call through a model:

On creation Memora validates the text and tags, adds a full-text search entry, computes an embedding, builds crossrefs to similar records and returns an identifier. It also warns about a possible duplicate: in the current code a similarity of 0.85 or above serves as the warning threshold.

But another tool is the genuinely interesting one. Instead of a blind insert you pass several atomic facts, and the system tries to reconcile them with the memory already accumulated:

Inside, the pipeline runs through several phases: first it tries to redact secrets in the fact automatically, then it builds an embedding and looks for similar existing records. An obvious high-similarity duplicate can be dropped without involving a model, while for ambiguous matches a model classifies the relationship. Depending on the verdict the new record either supersedes the old one, contradicts it, is simply linked to it, or becomes new knowledge. Several similar new facts are grouped along the way and may be merged into one denser record.

The practical benefit is clear: at the end of a session the agent hands over ten or twenty important results, and the memory layer itself tries not to turn the store into five hundred variations of the same thought.

Hybrid search

The project recommends hybrid search as the primary one - it combines search by meaning and by words:

The results of the two branches are fused by reciprocal rank fusion. By default the semantic weight is 0.6 and the keyword weight is therefore 0.4.

Why two branches? Semantic search understands paraphrasing well. Full-text search is better at catching exact names like refresh_token_v2, function names, error numbers and specific terms. Hybrid search takes the advantages of both. On top of that there are metadata filters, a date range, tag sets - any of the listed, all at once, or excluding - and a lineage mode.

memory_digest: assembling context in one call

memory_digest deserves a mention of its own, and its idea matters more than an ordinary "make a summary". It is a deterministic context assembler for a topic that preserves links to the source records:

Inside it runs a hybrid search on the topic, takes only active records, adds version chains when needed, walks graph relations a few hops out, separately collects related TODOs and issues, and returns a single list of source identifiers.

This is why those identifiers are fundamental: the agent gets not just ready context but the record numbers by which the original text can be requested and the digest checked for invention. It is a convenient way to start a new session - instead of fifteen separate search and list calls, the agent asks for one digest on the subsystem at hand.

Active versus stale

In a long-lived project old decisions do not vanish - they become history. Memora uses a typed supersession edge and follow modes:

There is also a dedicated memory_detect_supersessions tool. First it looks for similar pairs by embeddings, then a model decides whether one record really replaces another, and with enough confidence it may create the edge. By default the tool runs with dry_run=True - sensible caution for such a potentially destructive classification.

The knowledge graph, TODOs and issues

Memora stores explicit links between records:

The edge types are references, implements, supersedes, extends, contradicts, related_to. Besides manual links the system automatically builds similarity crossrefs - thanks to which the digest and the graph find not only the direct search hit but the decisions, reasons, implementation details and follow-up tasks connected to it.

Unfinished work is part of memory too, and it has dedicated tools rather than just the generic create:

For code work that is convenient: open items do not dissolve into general notes, and the digest can attach related TODOs and issues to a topic separately.

Documents, fragments and tags

A research report, an architectural decision or an incident review is awkward to cut into random pieces, so documents get their own pipeline:

Markdown is parsed by structure: tables may turn into separate claims, numbered lists into plan items, link lists into references, risk sections into risk fragments. The supported fragment kinds are claim, plan_item, reference, section_chunk, risk. The result is a useful combination - the whole document stays one logical artifact, while individual statements inside it are findable by semantic search. Fragments are protected from accidental destructive maintenance: deletion requires an explicit flag, merging does not combine them, and the duplicate and supersession pipelines skip them.

All of it is filed by a hierarchy of sections and subsections, and by tags with a slash separator:

When a record is created the system can suggest a hierarchy from similar existing records: in the current code, at a confidence of 0.5 or above the top option is applied automatically. If you want a strict taxonomy, set an allowlist through MEMORA_TAG_FILE or MEMORA_TAGS.

The graph in a browser, and chat over memory

If the server runs with graph support, the interface is available locally:

There you get a details panel with the record's content, metadata and links, a timeline, a history of every create, update, delete, merge, boost and link operation, a time slider, filters, real-time updates, Mermaid rendering and a chat. Node size reflects the number of links, and TODOs, issues and ordinary tags are visually distinct. For a store of hundreds of connected decisions that is not decoration: the graph helps spot clusters and unexpected links between parts of the project.

Chat over memory runs a semantic search, passes what it found to a model and streams the answer, while links of the form [Memory #ID] lead to the source record. More importantly, the model can call tools and, if asked, create, change or delete a record straight from the chat. That requires an OpenAI-compatible API and a model with function calling.

From which follows a simple security implication: this is already a write-capable interface. If the graph and chat are reachable by more than just you, that access must be protected - in the cloud variant the README plainly recommends Cloudflare Zero Trust.

Where memory lives, and which embeddings to pick

For D1 the environment gets the database address and a token:

For syncing through R2 or S3 - the endpoint address and the path to the file:

A separate choice is what computes semantic similarity.

It is set by a single variable:

If you change the model after records already exist, the embeddings and crossrefs have to be rebuilt:

A fully local setup

The main storage and search pipeline works locally. The lightest option is SQLite plus TF-IDF with no external API at all; better semantic retrieval comes from local sentence-transformers.

This mode switches off model-driven comparison. Creating, listing, searching and the graph remain, but operations that fundamentally need a model will not give the same intelligent result. That applies especially to smart absorption: it has to tell an update from a contradiction and merge related facts. If you need that whole pipeline locally, you will want a local endpoint with an OpenAI-compatible API, and it is worth testing separately with your chosen model.

Secrets, and events between agents

Before saving, Memora runs the content through a set of regular expressions. The current code tries to cover OpenAI, OpenRouter and Anthropic keys, AWS access keys, GitHub and Slack tokens, bearer tokens, private keys, plaintext passwords and secrets, and bank card numbers. A match is replaced with:

But this is not a full data-loss prevention system. Regular expressions do not recognise every possible secret or piece of personal data, so if the memory server is connected to an agent with access to production credentials, auto-redaction should not be treated as a guarantee.

For linking several agents there is a simple poll-based event system: in the current code the special shared-cache tag causes an event to be created on write. Another agent polls the events and then marks them consumed. This is neither a message broker nor a real-time orchestration layer, but for a couple of terminal agents it is enough: one finishes its research, the record appears, the second sees the event and picks up the new memory.

A memory store needs maintenance too

The toolset for that is fairly large: memory_find_duplicates looks for potential duplicates with optional model comparison, memory_merge combines records, memory_detect_supersessions finds decisions that replaced older ones, memory_clusters picks out groups of related records, memory_boost raises importance, memory_insights shows activity, stale tasks and consolidation candidates, memory_stats gives store statistics, and memory_export and memory_import handle transfer and backups.

For heavy maintenance operations the server code has cooldowns between calls, so the agent cannot run rebuilds, deduplication and insights in a tight loop and eat resources. The values sit right there in the cooldown table: five minutes for rebuilding embeddings, cross-references and image migration, two minutes for duplicate search and the activity digest, a minute for import and export, half a minute for supersession detection.

There are limits on the write itself too: content shorter than three characters is rejected, and the upper bound is fifty thousand characters per memory.

Licence, cost and limitations

The situation here is simpler than with some neighbours on the topic: the project and the package are published under MIT, and there is no mandatory separate closed backend in the repository - local SQLite and TF-IDF are part of the project. But external components cost money at their providers' rates: OpenAI embeddings, an OpenAI-compatible model, Cloudflare D1 and R2, S3. So a completely free local set is assembled like this: Memora, SQLite and TF-IDF. Or Memora, SQLite and local sentence-transformers, if you are ready for heavier dependencies.

The limitations are worth knowing up front too. The version is young, tool schemas and behaviour keep changing, so pinning the version in production is wise - and one example shows why that is not a formality. Release 0.3.0 forces a one-time rebuild of every stored embedding, and the reason is instructive: following its own README and installer, Memora could be configured so that no embedding was ever computed and nothing said so. The installer wrote an embedding model to be served through OpenRouter, which provides no embeddings endpoint - every call returned 404, the server logged one warning to stderr, silently fell back to TF-IDF and carried on. In the store where this was found, 756 memories had been keyword vectors for months while the system reported itself healthy. The model fingerprint is now stored alongside the data, so such a mismatch is detected. The moral is simple: after changing the embedding model, verify that semantic search is genuinely semantic. SQLite does not magically become a distributed database: a local file is excellent for one user and a few local agents, but it does not turn into a high-load multi-tenant store, and D1 solves a different part of the problem and means cloud deployment. A graph relation is not proven causality: some crossrefs are built from similarity, and if two records are alike that does not mean one really implements the other - explicit typed links are better but require careful writing. And finally, model-driven maintenance can be wrong: duplicate detection, supersession classification and fact reconciliation use a model, and it is good that the project returns confidence, reasoning and source identifiers and supports a dry run - but turning these operations into uncontrolled background magic is still unwise.

When Memora fits, and where to start

It is especially good where Claude Code and Codex must remember a project's decisions between sessions; where several MCP agents work against a shared knowledge base; where telling the current version of a decision from an old one matters; where tasks and bugs should sit next to architectural context; where the ability to check source identifiers matters more than trusting a magic summary; where you want to see the knowledge graph and change history with your own eyes; where large Markdown documents must be stored but individual statements inside them searched; where cloud access through D1 or R2 is needed without moving to a closed managed service.

It is sensible to start with one of three configurations. The simplest personal memory - zero external APIs, enough to understand Memora's model and keep notes, tasks and bugs:

A proper local semantic memory - search stays on the machine, and a model is needed only where smart reconciliation and duplicate detection are:

And memory shared across several computers - D1 is the cloud option the README itself recommends, while a hosted graph can receive real-time updates and be reachable from different machines:

Strip away the marketing and Memora's idea is pragmatic: make an agent's memory an ordinary maintainable information system - not only semantic search but storage, full-text search, metadata, tags, version lineage, typed relations, TODOs and issues, structured documents, backups, an event log and a UI. The strongest combination in the current version is four things: smart absorption saves new results and links them to old knowledge, supersession keeps the current decision from being confused with a historical one, hybrid search finds both meaning and exact technical terms, and the digest hands the next agent a verifiable bundle in one call. That is why Memora is most convincing precisely as memory for agents working with code: what matters there is not abstract user preferences but decisions, changes, bugs, open tasks, links between implementations, and the ability to see where every statement came from.

Sources

This article was checked against the current Memora repository, the README, SOUL.md, agent.yaml, the source of server.py and storage.py, and the release notes on 9 August 2026. Supplemented on 14 August 2026 against a fresh clone: the package version raised to the current one, and the number of published tools, the cooldown values for heavy operations and the limits on record length added.

• GitHub: agentic-box/memora
• README.md
• SOUL.md
• agent.yaml - the MCP tool manifest
• pyproject.toml
• memora/server.py
• memora/storage.py
• memora/document.py
• Releases
• MIT License