vishalbanwari26/mnemos

A persistent memory framework for LLM agents. It gives an agent episodic
memory (what was said, and when), semantic memory (distilled facts about the
user), procedural memory (which retrieval strategy actually works for this
user), and reflection (consolidating and forgetting facts over time) — backed
by a choice of three storage backends, exposed over a FastAPI surface, and
observable through a React dashboard. It ships with a benchmark that measures
whether the agent actually still remembers something 30 simulated days after
it was mentioned once — not just whether the demo looks good.
Most "agent memory" projects on GitHub are a vector store wrapped around a
chat loop with no way to tell if it's actually working. This one tries to
answer that question directly: seed a fact once, ask about it later, measure
recall and answer accuracy with and without memory, and report the delta.
See it work
Recorded live, against a real running dashboard, a live Postgres backend, and
a real hosted LLM (Groq, Llama 3.3 70B) — not staged, not a mockup. Demo data
was seeded across 7 simulated conversation sessions spanning 10 simulated
days: a chat turn correctly recalls a fact from one earlier session (the
user's dog) and a different fact from another earlier session (the
deployment stack), then the walkthrough moves through retrieval scoring,
memory stats, and the reflection audit trail.
Static screenshots of each view, for anyone who wants to pause and read the
numbers:
**It actually remembers across sessions,** and shows exactly which memories
it used and what it just learned.
**Retrieval isn't a black box.** Every retrieved memory ships with its real
similarity, recency, and combined score — this is the actual ranking the
chat loop uses, not a simplified illustration.
That transparency isn't just a dashboard view here — it's now a standalone
library, memlens, that traces
retrieval for any backend (mem0, raw pgvector, or mnemos itself): every
candidate considered, its full score breakdown, and whether it was included
or excluded and why.
**The system prunes itself.** Reflection has merged 4 pairs of near-duplicate
facts into single consolidated statements (via real LLM tool-use calls) and
decayed stale facts' confidence; a low-value fact that crossed the forget
threshold is now archived, not silently deleted.
**It knows what's in memory, and how that's changing.** Counts by type and
status, plus a growth-over-time chart, computed from the same demo data: 18
episodic memories, 18 active facts, 4 merged, 1 forgotten.
**It adapts its own retrieval strategy.** After live turns, the system
already has empirical uses/success-rate data on which similarity/recency
weighting works best for this user — the mechanism, not a placeholder.
Quickstart
Not on PyPI yet, so git clone is the install for now. No Docker, want the
full HTTP API + dashboard, or want to try the Qdrant/Neo4j backends instead?
See Running it below for all of that.
Why this exists
Chat agents without persistent memory forget everything between sessions.
Ask ChatGPT-style tools about something you told them yesterday and, unless
it happened to land in a fixed context window, it's gone. The interesting
systems question isn't "can I bolt a vector DB onto an LLM" — it's *how do
you decide what to keep, how do you retrieve it cheaply and correctly, how
do you forget responsibly, how do you adapt your own retrieval strategy from
feedback, and how do you prove any of it is working over time, not just in a
single session.*
This project started as a deliberately scoped v1 — two memory types, one
storage backend, one retrieval strategy, a benchmark — to prove the core
loop actually works before building anything else on top of it. It then grew
into the full system: procedural memory, reflection/forgetting, three
interchangeable storage backends, and a dashboard. See
What's intentionally out of scope for
what's still not here, and why.
Architecture
- **MemoryEngine** (src/mnemos/memory/engine.py) is the single seam
everything else talks to. It wraps a StorageBackend and an
EmbeddingClient. Nothing outside this file touches a backend or the
retriever directly — that's what let procedural memory, reflection, and two
extra storage backends get added later without rewiring every caller.
- **ConversationManager** (src/mnemos/agent/conversation.py) is the
per-turn loop: pick a retrieval strategy → recall relevant memories →