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

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:

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-bench repo
• 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.