Memora Agent Memory
A structured memory layer that stores rich agent history and retrieves it through abstractions and semantic cues.
The README identifies user IDs, sharing and isolation concepts, vector storage, and Azure/OpenAI configuration, while the paper, authors, MIT license, and Microsoft provenance provide strong source attribution. Full credit is not justified elsewhere because the supplied material does not demonstrate enforced least privilege, confirmation before writes or merges, complete third-party data-flow boundaries, encryption/redaction/retention controls, or rollback for automatic deduplication and updates. Dependencies are unpinned and no vulnerability-control evidence is shown; SECURITY.md supplies only a reporting route.
The installation, query, and experiment narratives are broadly coherent, but the Python 3.12 badge versus the >=3.10 prerequisite and the two different import forms reduce self-consistency. Dependencies are enumerated and the GPU requirement for GRPO is disclosed, yet versions, compatibility guarantees, and availability behavior are not supplied. There is no evidence of actionable failure messages, retries, fallback behavior, or error recovery.
The documentation thoroughly identifies agent developers and covers conversational and document memory, shared use, several retrieval strategies, and two benchmark scenarios. It marks GRPO as experimental and GPU-dependent, but boundaries around backend compatibility, privacy isolation, and automatic processing remain largely asserted. Explicit API calls provide some trigger clarity, while the timing and control of automatic extraction, segmentation, merging, and updating are underspecified. Python, Azure/OpenAI, environment variables, Hydra, and one platform-specific dependency are covered, but a complete platform and version compatibility matrix is absent.
The README has strong sectioning, a project tree, configuration tables, and task-oriented entry points. Installation and examples are useful for ordinary onboarding, but essential cfg construction is deferred to quickstart.py, whose contents are not supplied, and there is no FAQ. The differing memora.memora_client and memora import forms leave the stable public naming surface unclear. GRPO is labeled experimental and GPU-dependent, but known limitations are not systematically documented. The full MIT license is present. No versioning policy or changelog is shown; Microsoft provenance and the security-reporting path clarify organizational responsibility, but named maintainers, support commitments, and release cadence are absent.
The result iteration example, agent integration pattern, and memory-to-prompt workflow make the intended outputs usable. Separating memory values, primary abstractions, and cue anchors presents plausible marginal value over a plain vector store, but the supplied files contain no benchmark results or comparative measurements substantiating that benefit. Cloud model calls, vector storage, and optional GPU training have material costs, while latency, price, and operational tradeoffs are not quantified.
The central design is traceable to a named paper, and the README points to concrete modules, configuration directories, and benchmark entry points. The license and security process receive independent file-level corroboration, but functional claims about accuracy, isolation, and backend flexibility appear mainly in the README without supporting tests, results, or other supplied sources. GRPO is clearly labeled experimental, although several comparative and effectiveness claims are not cleanly separated from unverified assertions.
- Memory content may be sent to OpenAI or Azure services and stored in ChromaDB or Redis; independently verify actual data flows, access isolation, retention, deletion, and encryption before processing personal or confidential data.
- requirements.txt is entirely unpinned. Establish a lockfile, software bill of materials, and vulnerability-scanning process, and validate Python, GPU, and backend compatibility before deployment.
- Automatic deduplication, merging, and updating may modify stored memories, but confirmation, audit, and rollback controls are not documented. Add backups, change records, and recovery controls for production use.
- Performance, precision, and flexibility claims in the README are not corroborated by supplied tests or benchmark results, and this static assessment did not execute the code.
What does this agent do, and when should you use it?
Memora is a Python memory framework for AI agents built around a three-part representation: memory values, primary abstractions, and cue anchors. Full-fidelity information remains in an unindexed memory value, while indexed abstractions and cues provide the structure used for organization, updates, and retrieval. Its library includes MemoraClient, chat and document builders, document processors, ChromaDB and Redis clients, and semantic, prompted, hybrid, and experimental GRPO retrieval components. Applications write conversations or documents through the Python API, retrieve relevant entries, and inject them into their own model prompts; Memora does not define a complete agent runtime or end-user interface. The source distribution also contains Hydra-configured runners for the LoCoMo and LongMemEval benchmarks.
The lifecycle begins with MemoraClient.add(context, type="doc"). Memora processes conversations or documents, segments conversations into topical episodes, and extracts factual, episodic, and procedural information into entries containing a memory value, primary abstraction, and cue anchors. It stores memories with semantic embeddings in ChromaDB, deduplicates, merges, and updates entries, and can maintain a cue index that maps higher-level cues to memories. MemoraClient.query(context, top_k=5) performs semantic retrieval, while MemoraClient.advance_query(...) exposes prompted, hybrid, or experimental GRPO strategies. Prompted retrieval uses an LLM-driven iterative policy, hybrid retrieval combines semantic similarity with BM25 or keyword matching, and GRPO can load a trained local retrieval-policy checkpoint. The returned entries expose fields such as entry.index and entry.value; the host application is responsible for inserting them into a prompt and producing the final response. The repository also includes processors for PDF, DOCX, Excel, Markdown, and other document formats, an interactive memory-store browser, and benchmark experiment runners.
- A Python team building a conversational assistant can retrieve a user's history before each response and save the completed exchange afterward.
- Long-context memory researchers can use the LoCoMo and LongMemEval runners to test semantic, prompted, or cue-indexed retrieval configurations.
- Engineers building a multi-agent environment can expose a unified memory space to several agents while scoping access by agent or role.
- Applications that retain facts, episodes, and procedures can preserve detailed source information in memory values while retrieving through abstractions and cues.
- Teams with GPU capacity can collect and score retrieval trajectories, then train a Qwen 3B/7B policy with GRPO and LoRA.
What are this agent's strengths and limitations?
- Its separation of unindexed memory values from indexed primary abstractions and cue anchors preserves source detail without embedding the full raw content directly.
- Memora covers ingestion, segmentation, deduplication, merging, updates, retrieval, and result formatting behind the relatively small MemoraClient interface.
- It offers semantic, LLM-prompted, semantic-plus-BM25 hybrid, and experimental learned retrieval paths for different recall and execution requirements.
- A shared memory space, agent or role scoping, and support for local or remote storage configurations make it applicable to multi-agent environments.
- LoCoMo and LongMemEval runners are included for testing configurations against established long-term-memory benchmarks.
- The documented standard setup depends on OpenAI API or Azure OpenAI model and embedding services, requiring credentials, network access, and paid external calls.
- Prompted retrieval performs iterative LLM-guided searches, which can add latency and model-call expense compared with one-pass semantic retrieval.
- The GRPO path is explicitly experimental; training requires a GPU and adds trajectory collection, scoring, LoRA training, and checkpoint-management work.
- The host application must still implement answer generation, prompt assembly, and the surrounding agent loop; this is not a ready-made chat application or full agent runtime.
- Migrating an existing memory system requires integration work and conversion into Memora's value, abstraction, and cue representation, with ChromaDB and embedding configuration in the documented flow.
How do you install or deploy this agent?
Python >= 3.10 is required. Install from source with:
git clone https://github.com/microsoft/Memora
cd Memorapip install -e .
For the documented standard configurations, set up either OpenAI API or Azure OpenAI. With OpenAI, run export OPENAI_API_KEY="sk-..." and configure openai.api_type: "openai", openai.api_key: "${oc.env:OPENAI_API_KEY}", and openai.embedding_model: "text-embedding-3-small" in YAML. For Azure, set AZURE_OPENAI_ENDPOINT and AZURE_MANAGED_IDENTITY_CLIENT_ID, then configure the chat and embedding endpoints, API version, deployment name, and embedding model. A GPU is explicitly required only for training the experimental GRPO policy.
How do you use this agent?
Construct the cfg object as demonstrated in quickstart.py, then run:
from memora.memora_client import MemoraClientmemory_client = MemoraClient(cfg=cfg, user_id="my_user")
memory_client.add("Alice is moving to Seattle for a new job.", type="doc")
results = memory_client.query("Where is Alice moving?", top_k=5)for entry in results:
print(f"{entry.index}: {entry.value}")For prompted retrieval, call memory_client.advance_query("Where is Alice moving?", query_type="prompt", top_k=5). In an agent loop, call query before response generation, place the returned memories in the host application's prompt, and save the combined User and Assistant exchange afterward with add(..., type="doc"). To run the documented LoCoMo example, enter app/locomo and execute python run_memora.py llm.model="gpt-4.1-mini" memory.memory_store="memora-cue" memory.enable_cue_index=True retrieval.strategy="prompt".
How does this agent compare with similar options?
Unlike RAG pipelines or flat stores that directly index all memory content, Memora keeps the full memory value unindexed and indexes a one-to-one primary abstraction plus many-to-many cue anchors. Compared with graph-based knowledge bases, it uses a lighter scaffolding layer and does not require the underlying memory to conform to a fixed graph structure. The intended tradeoff is richer retained detail with more controlled retrieval entry points; adopters should validate the practical result with the included LoCoMo or LongMemEval experiments.