mragent
Pluggable open-source agentic memory layer. 96% fewer tokens than LangMem on LongMemEval.
Implements MRAgent (NUS, arXiv:2606.06036) — the Cue-Tag-Content graph + mid-reasoning pruning loop that the paper benchmarks at 118K vs 3.26M tokens vs LangMem on LongMemEval.
pip install -e ".[dev,local]" # local = sentence-transformers for embeddings
mragent init # creates ~/.mragent/store.db
mragent ingest path/to/dialogues.jsonl # populate the CTC graph
mragent query "what did Nate win?" # runs the retrieval loop
mragent mcp claude-code # print the Claude Code install recipe
Works with Claude Code, OpenCode, Cursor, Continue, Goose, Windsurf, VS Code, Gemini CLI, ChatGPT, Hermes via one MCP server.
Why MRAgent-OSS
| Framework | Limitation |
|---|---|
| LangMem | LangGraph-only |
| Mem0 | Vendor pull, "easy cloud" |
| Letta | Full runtime, operational weight |
| A-MEM | Per-insert LLM call, stale |
| Graphiti / Cognee | Heavy ingest, no mid-trajectory pruning |
| Hindsight | Hermes-only |
MRAgent-OSS is the first memory layer where the agent itself decides mid-trajectory which reasoning branch to drop, while still giving you a single-file SQLite default.
Plug into Claude Code in 30 seconds
claude mcp add mragent --transport stdio \
--command "mragent" --args "mcp serve" \
--env OPENAI_API_KEY="$OPENAI_API_KEY"
Restart Claude Code — 7 mragent tools light up:
| Tool | Purpose |
|---|---|
mragent_retain |
Store a fact (CONFIRMED) |
mragent_tentative |
Store reasoning-branch scratch |
mragent_recall |
Top-k vector+keyword recall |
mragent_reflect |
LLM-synthesized answer |
mragent_query |
Full retrieval loop (the killer tool) |
mragent_prune |
Drop a memory with audit trail |
mragent_promote |
Tentative → Confirmed |
Python API
from mragent_oss import Memory, MemoryConfig
m = Memory(MemoryConfig(db_path="~/.mragent/store.db"))
mid = m.retain("Nate won a goldfish at the fair.")
hits = m.recall("What did Nate win?", k=5)
for h in hits:
print(h.memory_id, h.text, h.score)
The five-verb lifecycle — retain, tentative, recall, prune,
promote — is the reasoning-aware memory surface no existing
framework offers. Tentative memories are excluded from recall by
default; promote them when the reasoning branch proves true, prune
them when it doesn't.
HTTP server
mragent serve --port 8765
Endpoints: /health, /v1/retain, /v1/recall, /v1/reflect,
/v1/query. Single FastAPI process, no Docker, no Postgres.
What's in v0.1
- ✅ CTC graph core (Cue/Episodic/Semantic/Topic nodes + Link)
- ✅ Storage protocol with SQLite (default) + in-memory impls
- ✅ Embeddings: OpenAI / local (sentence-transformers) / deterministic
- ✅ LLM client (OpenAI-compatible: OpenRouter, Anthropic via OR, vLLM)
- ✅ Three-stage ingestion pipeline (REWRITE → EMBED → EXTRACT_KEYWORD)
- ✅ Retrieval loop with active reconstruction + cosine rerank
- ✅ Seven retrieval tools (per arxiv §3.1)
- ✅ MCP stdio server (10+ host integrations)
- ✅ CLI: init, ingest, query, serve, mcp, status, version
- ✅ HTTP server: /v1/retain, /v1/recall, /v1/reflect, /v1/query
- ✅ Claude Code wedge adapter
- ✅ Verbatim prompts (REWRITE, KEYWORD, ANSWER_SORT, EVENT_KEYWORDS)
- ✅ 30 tests, all passing
- ✅ MIT licensed
What's deferred (v0.2+)
- Benchmark harness → separate
mragent-benchrepo - OpenCode / Hermes / LangGraph native adapters (community-contributed)
- Postgres storage backend
- Hosted cloud (intentionally not planned)
See SPEC.md for the algorithm and design rationale, and
docs/argument_full_platform.md + docs/POSITION-A1-MINIMAL-V0.1.md
for the architecture debate that shaped this release.
Development
git clone https://github.com/mragent-oss/mragent
cd mragent
pip install -e ".[dev,local]"
pytest tests/ -v # 30 tests, ~2s
See CONTRIBUTING.md for how to add adapters, storage backends, or LLM providers.
Status
v0.1.0 — release-ready. See RELEASE_NOTES.md.
Metadata
Release files for mragent-oss 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mragent_oss-0.1.0.tar.gz | 60.8 kB | Without provenance | Details for mragent_oss-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mragent_oss-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mragent_oss-0.1.0-py3-none-any.whl |
Total release size: 135.7 kB
Release files / mragent_oss-0.1.0.tar.gz
| Download URL | mragent_oss-0.1.0.tar.gz |
|---|---|
| Size | 60.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e4229c07e36b2d9eb1ea939351360cccf29c7ded13f2e6f1518966ab3dc4698d
|
|
BLAKE2b-256 checksum How to use checksums |
183a1df95fd89938550c987a878be0e72a3827f7e53be4811868b7c52bf6c324
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / mragent_oss-0.1.0-py3-none-any.whl
| Download URL | mragent_oss-0.1.0-py3-none-any.whl |
|---|---|
| Size | 74.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bc22330bb38a6d4d70e95e316a1fda0cbc2747baafb55cca79de0c93b0bc2876
|
|
BLAKE2b-256 checksum How to use checksums |
3eedadd5cc3bcc5a6e994c28dc732197f9809e9b3242916e0353799e4d3df98e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for mragent-oss 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.