---
license: mit
library_name: mnemo
tags:
  - llm
  - agent-memory
  - rag
  - mcp
  - memory-poisoning
  - agent-security
---

# mnemo — a zero-dependency memory layer for AI agents

`pip install agora-mnemo` · [PyPI](https://pypi.org/project/agora-mnemo/) · [GitHub](https://github.com/DanceNitra/agora/tree/main/mnemo) · MIT

mnemo is the recall + consolidation core of an autonomous research system, distilled to a **single
dependency-free Python file** plus an MCP server so any Claude / Cursor / agent can use it as memory.
Its design rules are **measured, not assumed** (provenance + runnable probes in the repo).

- **Value-ranked recall** — top-k by relevance × accrued value, not cosine alone.
- **Per-type decay + capacity-aware consolidation** — the "dream" pass links near-duplicates and marks
  stale/superseded, never rewriting the raw note.
- **Lexical + semantic auto-mode** — BM25 + embeddings fused by Reciprocal Rank Fusion.
- **Contradiction flagging** — mutually-incompatible memories surface for review, never auto-deleted.
- **Corroboration-gated influence (0.4.0)** — `recall(influence_only=True)` restricts the memories
  allowed to *drive an action* to those that earned corroboration (a credited good outcome, or ≥2
  distinct-source links).

## Why 0.4.0 matters: poison-resistant recall

We red-teamed mnemo with a real AgentPoison-style single-instance memory-poisoning attack (Chen et al.,
NeurIPS 2024; PoisonedRAG, Zou et al., USENIX Security 2025). Findings, all with runnable receipts:

- A **plain-English trigger sentence** in one poisoned memory hijacks raw top-1 retrieval **88–100%**,
  is **scale-invariant** (60→10 000 memories), and **evades a perplexity filter**.
- Retrieval-time / embedding-geometry defenses **do not generalize** across encoders.
- `recall(influence_only=True)` drops the single-instance poison's rank-1 hijack to **0%** on
  MiniLM / BGE / Contriever and every scale — because it lives in **provenance metadata, not embedding
  geometry**. Honest cost: a rare-but-true memory that hasn't earned corroboration is filtered too
  (recall 1.00 corroborated vs 0.08 uncorroborated), so this mode is for adversarial / untrusted
  ingestion. It **raises** attacker cost (≥3 coordinated records + ≥2 forged independent provenances),
  it does not make poisoning impossible.

```python
from mnemo import Mnemo
m = Mnemo("memory.json")                      # or Mnemo(..., embed=my_embedder)
m.remember("Pre-trend tests catch only ~31% of fatal DiD bias.", tags=["causal"], value=3)
m.recall("difference in differences", k=5)
m.recall("difference in differences", k=5, influence_only=True)   # only corroborated memory drives actions
```

Part of [Agora](https://github.com/DanceNitra/agora). MIT-licensed.