Metadata-Version: 2.5
Name: mragent-oss
Version: 0.1.0
Summary: Pluggable open-source agentic memory layer — MRAgent (arXiv:2606.06036)
Project-URL: Homepage, https://github.com/shanewas/mragent
Project-URL: Source, https://github.com/shanewas/mragent
Project-URL: Issues, https://github.com/shanewas/mragent/issues
Project-URL: Changelog, https://github.com/shanewas/mragent/blob/main/RELEASE_NOTES.md
Author-email: Shanewas Ahmed <shanewasahmed@gmail.com>
Maintainer-email: Shanewas Ahmed <shanewasahmed@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,llm,long-term-memory,mcp,memory,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: openai>=1.30
Requires-Dist: pydantic>=2.6
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: sentence-transformers>=2.7; extra == 'local'
Description-Content-Type: text/markdown

# 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.

```bash
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

```bash
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

```python
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

```bash
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

```bash
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`.