memarena 0.1.2__tar.gz

memarena-0.1.2/.gitignore

@@ -0,0 +1,14 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+node_modules/
+viewer/dist/
+memarena-out/
+site/
+*.egg-info/
+.DS_Store

memarena-0.1.2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.2 - 2026-11-03
+
+- Include LongMemEval MIT notice with the bundled demo data
+  (`src/memarena/data/demo/LICENSE-LongMemEval.txt`, copied unmodified from xiaowu0162/LongMemEval) and cite it
+  in a "Third-party data" section of the README.
+
+## 0.1.1 - 2026-11-03
+
+- Terminal: `memarena demo` and `run` fit narrow terminals (80 columns, CI logs, pipes). Below 150 columns the
+  per-category accuracy moves to a second table; below 100 columns p50 and ingestion time are dropped.
+- Viewer: the judge audit is stored as structured data and shown in the viewer's language (EN/ES).
+- Viewer: system cards share one layout (kind chip under the name), so they line up.
+- Viewer: answers render the bold/italic/code markdown models emit instead of showing raw asterisks; latency and
+  token counts sit on their own line in every answer card; the question field is labelled "Question"; Spanish
+  cards say "correctas".
+- Viewer: deep links `#questions`, `#method` and `#q=<question id>` open a tab or expand a question.
+
+## 0.1.0 - 2026-11-03
+
+First release.
+
+- Importers: ChatGPT export, Claude export (`conversations.json` or the `.zip`), generic JSONL.
+- `memarena generate`: questions with gold answers and evidence pointers in LongMemEval's five categories
+  (single-session, multi-session, temporal, knowledge update, abstention), written as `pending` for review.
+- `memarena run`: systems mem0 (OSS), Letta (REST API) and Supermemory (API), always next to three baselines:
+  full context, BM25 and embeddings. Same answer model and prompt for every system.
+- Metrics: accuracy from an LLM judge (prompt published in `docs/judge-prompt.md`), retrieval latency p50/p95,
+  ingestion time, prompt tokens and cost, overall and per category.
+- Viewer (React) bundled in the wheel: `memarena view`, question review and editing, static export for Pages.
+- `memarena demo`: a recorded real run on a 20-question LongMemEval subset (MIT).
+- `--max-cost` budget checked before every paid call, privacy warning before sending data to a cloud provider.

memarena-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Pérez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memarena-0.1.2/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: memarena
+Version: 0.1.2
+Summary: Benchmark memory layers on your own conversations, not on someone else's leaderboard.
+Project-URL: Homepage, https://diegoperezg7.github.io/memarena/
+Project-URL: Repository, https://github.com/diegoperezg7/memarena
+Project-URL: Issues, https://github.com/diegoperezg7/memarena/issues
+Project-URL: Changelog, https://github.com/diegoperezg7/memarena/blob/main/CHANGELOG.md
+Author: Diego Pérez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,benchmark,evaluation,letta,llm,mem0,memory,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: openai==3.42.1
+Requires-Dist: rich==15.0.0
+Requires-Dist: typer==0.27.3
+Provides-Extra: letta
+Requires-Dist: letta-client==1.12.1; extra == 'letta'
+Provides-Extra: mem0
+Requires-Dist: mem0ai==2.2.1; extra == 'mem0'
+Requires-Dist: ollama==0.6.3; extra == 'mem0'
+Provides-Extra: supermemory
+Requires-Dist: supermemory==5.0.1; extra == 'supermemory'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="memarena" width="760">
+</p>
+
+<p align="center">
+  <a href="https://github.com/diegoperezg7/memarena/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/diegoperezg7/memarena/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7945c5"></a>
+  <a href="https://github.com/diegoperezg7/memarena/releases"><img alt="Release" src="https://img.shields.io/github/v/release/diegoperezg7/memarena?color=7945c5"></a>
+  <a href="https://github.com/diegoperezg7/memarena/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/diegoperezg7/memarena?style=flat&color=7945c5"></a>
+</p>
+
+<p align="center"><b>Benchmark memory layers on your own conversations, not on someone else's leaderboard.</b></p>
+
+<p align="center">English · <a href="README.es.md">Español</a> · <a href="https://diegoperezg7.github.io/memarena/">Live example viewer</a></p>
+
+memarena turns your ChatGPT or Claude export into a memory test: it writes questions with gold answers
+from your own history (you review them), feeds the history to each memory layer, asks every question and
+grades the answers with a published LLM-judge prompt. Every run also includes the two things a memory layer
+has to beat: **pasting the whole history** and **simple retrieval** (BM25 and embeddings).
+
+![memarena viewer, recorded demo](docs/assets/screenshot-light.png)
+
+## Why
+
+The public memory harnesses are each published by a memory vendor and are built around fixed datasets:
+[supermemoryai/memorybench](https://github.com/supermemoryai/memorybench) (334 stars, Supermemory),
+[vectorize-io/agent-memory-benchmark](https://github.com/vectorize-io/agent-memory-benchmark) (163, Vectorize) and
+[mem0ai/memory-benchmarks](https://github.com/mem0ai/memory-benchmarks) (134, Mem0) (star counts checked 2026-11-03).
+
+Vendor numbers do not agree with each other. Mem0's paper reports, on LoCoMo, a 26% relative improvement in
+LLM-as-a-Judge over OpenAI's memory and 91% lower p95 latency with over 90% fewer tokens than full context
+([arXiv 2504.19413](https://arxiv.org/abs/2504.19413)). Letta then reported 74.0% on LoCoMo with GPT-4o mini for a
+plain filesystem agent, against the 68.5% Mem0 published for itself, adding that
+"Mem0 did not respond to requests for clarification"
+([Letta blog, 12 Aug 2025](https://www.letta.com/blog/benchmarking-ai-agent-memory)). Zep reports 94.8% on DMR vs
+93.4% for MemGPT and up to 18.5% higher accuracy on LongMemEval ([arXiv 2501.13956](https://arxiv.org/abs/2501.13956)).
+
+Whichever is right on LoCoMo, none of it tells you how a memory layer does on **your** conversations, with
+**your** model, against the cheap option of pasting everything. memarena is vendor-neutral, runs on your
+exports, and always puts full context, BM25 and embeddings in the same table.
+
+## Quickstart
+
+Recorded demo, no keys, no Docker, no model calls (under 2 minutes from a clean machine with `uv`):
+
+```bash
+uvx --from git+https://github.com/diegoperezg7/memarena@v0.1.2 memarena demo
+```
+
+or from a clone:
+
+```bash
+git clone https://github.com/diegoperezg7/memarena && cd memarena && uv run memarena demo
+```
+
+![memarena demo in the terminal](docs/assets/demo.gif)
+
+It prints the table below and opens the viewer on http://127.0.0.1:8765 (add `--no-view` to only print).
+`uvx memarena` is coming to PyPI.
+
+## Example output
+
+This is a **recorded real run** (`memarena run`, 2026-11-03), shipped in the package and shown by `memarena demo`:
+20 questions (4 per category) from [LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned)
+(MIT), with the evidence sessions of all 20 merged into **one** history of 28 sessions (~75k tokens), the way a
+single user's export looks.
+
+| System | Accuracy | Single | Multi | Temporal | Update | Abstain | Retrieval p50 / p95 | Ingest | Prompt tokens / q | Cost |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| **mem0** (memory layer) | **75%** | 50% | 50% | 75% | 100% | 100% | 49 / 134 ms | 21.6 min | 611 | $0.174 |
+| bm25 (baseline) | 70% | 75% | 25% | 50% | 100% | 100% | 0.9 / 3.9 ms | 0.03 s | 4,180 | $0.008 |
+| embeddings (baseline) | 55% | 50% | 50% | 25% | 50% | 100% | 105 / 233 ms | 34 s | 3,537 | $0.007 |
+| full-context (baseline) | 50% | 0% | 0% | 75% | 75% | 100% | 0.5 / 1.2 ms | 0 s | 69,297 | $0.139 |
+
+Setup: answer model `mistral/ministral-8b-latest` (same for every system), judge `mistral/codestral-latest`,
+mem0 2.2.1 with `ministral-8b-latest` for fact extraction, embeddings `nomic-embed-text` on local Ollama, top 10
+items per retriever. Hardware: Apple silicon laptop, 10 CPUs, 16 GB RAM; the local Ollama server was shared with
+other jobs during the run, so the embedding latencies are pessimistic. 20 questions is a small sample: treat
+differences of one or two questions as noise.
+
+What this small run shows:
+
+- **Pasting everything lost.** With ~69k prompt tokens per question, the 8B answer model said "I don't know" to
+  every single-session and multi-session question, while answering the same questions from retrieved snippets.
+- **mem0 sent about 1% of the full-context prompt** (611 vs 69,297 tokens per question) and scored highest, but
+  its ingestion took 21.6 minutes and $0.17 of LLM calls for 165 turns (one extraction call per turn), against
+  0.03 s for BM25.
+- **BM25 was 5 points behind mem0** at almost no cost. That gap is one question.
+- **Judge audit.** I checked all 80 judge decisions by hand: 3 false positives, all temporal (one each for
+  full-context, bm25 and mem0, e.g. "about 1 week ago" accepted for "4 weeks"), and no false negatives. Corrected
+  accuracy: mem0 70%, bm25 65%, embeddings 55%, full-context 45%. The order does not change. The table shows the
+  judge's raw output, as the tool produced it.
+- Total spent on this run: **$0.34** (Mistral API, priced from the token counts it returned).
+
+Browse every answer, the judge's reasoning and what each system retrieved in the
+[example viewer](https://diegoperezg7.github.io/memarena/).
+
+## Use it on your own history
+
+```bash
+# 1. Import your export (ChatGPT or Claude conversations.json, the export .zip, or JSONL)
+uvx --from git+https://github.com/diegoperezg7/memarena@v0.1.2 memarena import conversations.json --out history.json
+
+# 2. Generate questions with gold answers and evidence pointers (written as "pending")
+memarena generate history.json --out questions.json            # local Ollama by default
+
+# 3. Review them: edit, approve or reject in the viewer (saved back to questions.json)
+memarena view --questions questions.json --history history.json
+
+# 4. Run the benchmark on the approved questions
+memarena run history.json questions.json --systems full-context,bm25,embeddings,mem0
+
+# 5. Look at the results, or export a static site
+memarena view results.json
+memarena export results.json --questions questions.json --out site
+```
+
+mem0, Letta and Supermemory are optional extras: run with
+`uvx --from 'memarena[mem0] @ git+https://github.com/diegoperezg7/memarena@v0.1.2' memarena run ...`
+(or `uv sync --extra mem0` in a clone).
+
+**Privacy.** With `--provider ollama` and local systems nothing leaves your machine. With a cloud provider,
+Supermemory or Letta Cloud, memarena lists where your conversations will go and asks before sending
+(`--yes` skips the question). Generated questions must be reviewed: an unreviewed question set makes the
+benchmark unreliable, so `run` only uses approved questions unless you pass `--include-pending`.
+
+## How it works
+
+```mermaid
+flowchart LR
+  E["ChatGPT / Claude export<br/>or JSONL"] -->|memarena import| H[(history.json)]
+  H -->|memarena generate| Q[(questions.json<br/>pending)]
+  Q -->|review in viewer| QA[(questions.json<br/>approved)]
+  H --> I{ingest}
+  I --> FC[full context]
+  I --> BM[BM25]
+  I --> EM[embeddings]
+  I --> M0[mem0]
+  I --> LE[Letta]
+  I --> SM[Supermemory]
+  QA --> RQ{retrieve per question}
+  FC & BM & EM & M0 & LE & SM --> RQ
+  RQ -->|same answer model + prompt| A[answers]
+  A -->|LLM judge, published prompt| R[(results.json)]
+  R --> V[viewer / static site]
+```
+
+- **Same answer model for everyone.** A system only decides what context reaches the answer model, so accuracy
+  differences come from memory, not prompting.
+- **Questions** follow LongMemEval's categories: single-session, multi-session, temporal, knowledge update and
+  abstention (the answer is not in the history and the right reply is "I don't know").
+- **Metrics**: accuracy from the LLM judge ([exact prompt](docs/judge-prompt.md)), retrieval latency p50/p95,
+  ingestion time, prompt tokens per question and cost, overall and per category.
+- **Budget**: `--max-cost` (default 1 USD) is checked before every paid call; when it would be exceeded the run
+  stops and keeps partial results. Local models count as 0.
+
+## Systems
+
+| System | Kind | Runs | Status in v0.1 |
+|---|---|---|---|
+| `full-context` | baseline | anywhere | whole history pasted, newest kept if over `--max-context-tokens` |
+| `bm25` | baseline | local, no deps | Okapi BM25 over user/assistant turn pairs |
+| `embeddings` | baseline | Ollama or any OpenAI-compatible embeddings | cosine search over turn pairs |
+| `mem0` | memory | local (mem0ai 2.2.1 OSS, Qdrant on disk) | live-tested (recorded demo); also smoke-tested with Ollama |
+| `letta` | memory | Letta REST API (letta-client 1.12.1) | **not live-tested**: mock-tested only, see below |
+| `supermemory` | memory | Supermemory API (supermemory 5.0.1), needs `SUPERMEMORY_API_KEY` | **not live-tested**: no key was available, mock-tested only |
+
+Notes found while building the adapters:
+
+- **mem0 and OpenRouter.** mem0 2.2.1's OpenAI-compatible client switches to OpenRouter whenever
+  `OPENROUTER_API_KEY` is set in the environment, ignoring the configured base URL. memarena hides that variable
+  from mem0 unless you chose OpenRouter, so your history goes only where you said. mem0's telemetry is turned off.
+- **mem0 defaults.** memarena tests mem0's default install. Its BM25 keyword search and spaCy lemmatization need
+  the `mem0ai[nlp,extras]` extras, which v0.1 does not install, so mem0 runs with semantic search only.
+- **Letta.** Since 0.34 the `letta/letta` Docker image and the `letta` PyPI package ship "Letta Code"; the old
+  self-hosted Python REST server is end-of-life (the image says so when you start it the old way). The adapter
+  uses the REST API through `letta-client`, so it needs Letta Cloud (`LETTA_API_KEY`) or a self-hosted server
+  that still exposes `/v1`. It writes each turn to the agent's archival memory and searches it; it does not drive
+  the agent loop.
+
+## Configuration
+
+| Option | Default | What it does |
+|---|---|---|
+| `--provider`, `--model` | `ollama`, `qwen3:4b` | answer model (also used by `generate`) |
+| `--judge-provider`, `--judge-model` | same as answer model | judge |
+| `--embed-provider`, `--embed-model` | `ollama`, `nomic-embed-text` | embeddings baseline and mem0's embedder |
+| `--memory-provider`, `--memory-model` | `ollama`, `qwen3:4b` | LLM inside mem0 / Letta |
+| `--systems` | `full-context,bm25,embeddings,mem0` | what to compare |
+| `--top-k` | 10 | items each retriever returns |
+| `--max-context-tokens` | 100000 | cap for the full-context baseline |
+| `--max-cost` | 1.0 | USD budget, checked before every paid call |
+| `--price in,out` | built-in table | override the USD-per-million-token price of the answer model |
+
+Providers (one OpenAI-compatible client, keys only from environment variables, see [.env.example](.env.example)):
+`ollama` (`OLLAMA_HOST`, default http://localhost:11434), `openai` (`OPENAI_API_KEY`), `openrouter`
+(`OPENROUTER_API_KEY`), `mistral` (`MISTRAL_API_KEY`). Optional systems: `SUPERMEMORY_API_KEY`, `LETTA_API_KEY`,
+`LETTA_BASE_URL`. memarena sends no telemetry.
+
+**Ollama context window.** Ollama serves models with a small default window (4096 tokens for `qwen3:4b` here) and
+its OpenAI-compatible `/v1` endpoint cannot change it per request, so long prompts are cut silently. Create a
+variant with a bigger window once (it shares the weights, no extra disk) and point memarena at it:
+
+```bash
+printf 'FROM qwen3:4b\nPARAMETER num_ctx 16384\n' > Modelfile && ollama create qwen3:4b-16k -f Modelfile
+memarena run history.json questions.json --model qwen3:4b-16k --memory-model qwen3:4b-16k \
+  --max-context-tokens 12000 --num-ctx 16384
+```
+
+Keep `--max-context-tokens` below the window (leave room for the question and the answer) so the full-context
+baseline truncates visibly in the results instead of silently on the server, and keep `--num-ctx` equal to the
+variant's window so mem0's calls do not force Ollama to reload the model. Local reasoning models such as qwen3
+think before answering, which is slow on a laptop. The recorded demo did not use Ollama for chat: its answer model
+(`ministral-8b-latest`, 128k window) received at most ~69.3k prompt tokens per question, so nothing was cut.
+
+Reproduce the demo data and run:
+
+```bash
+curl -LO https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_oracle.json
+memarena longmemeval longmemeval_oracle.json --out-dir lme --per-category 4 --max-chars 16000
+memarena run lme/history.json lme/questions.json --systems full-context,bm25,embeddings,mem0 \
+  --provider mistral --model ministral-8b-latest --judge-model codestral-latest \
+  --memory-provider mistral --memory-model ministral-8b-latest --yes --max-cost 2
+```
+
+## Roadmap
+
+- More memory systems: Zep / Graphiti (need Neo4j or FalkorDB), cognee, MemOS.
+- claude-mem is out of scope for now: it is a Claude Code session plugin, not an API to ingest conversations.
+- Letta agent-loop mode (let the agent edit its own memory while reading the history).
+- mem0 with its `nlp` and `extras` (hybrid search) as a separate configuration.
+- Repeated runs with confidence intervals.
+- LoCoMo is not bundled: its license (CC BY-NC 4.0) is not compatible with an MIT package.
+
+## Third-party data
+
+The recorded demo bundles a 20-question subset of LongMemEval
+([xiaowu0162/longmemeval-cleaned](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned), code at
+[xiaowu0162/LongMemEval](https://github.com/xiaowu0162/LongMemEval)), MIT licensed, Copyright (c) 2024 Di Wu.
+Its license notice ships next to the data, unmodified, in
+[`src/memarena/data/demo/LICENSE-LongMemEval.txt`](src/memarena/data/demo/LICENSE-LongMemEval.txt)
+(copied from the LongMemEval repository at commit `9e0b455`), and is included in the wheel and the sdist.
+
+## License
+
+[MIT](LICENSE) for memarena itself. The bundled demo data keeps its own MIT notice (see Third-party data).

memarena-0.1.2/README.es.md

@@ -0,0 +1,253 @@
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="memarena" width="760">
+</p>
+
+<p align="center">
+  <a href="https://github.com/diegoperezg7/memarena/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/diegoperezg7/memarena/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="Licencia: MIT" src="https://img.shields.io/badge/license-MIT-7945c5"></a>
+  <a href="https://github.com/diegoperezg7/memarena/releases"><img alt="Release" src="https://img.shields.io/github/v/release/diegoperezg7/memarena?color=7945c5"></a>
+  <a href="https://github.com/diegoperezg7/memarena/stargazers"><img alt="Estrellas" src="https://img.shields.io/github/stars/diegoperezg7/memarena?style=flat&color=7945c5"></a>
+</p>
+
+<p align="center"><b>Compara capas de memoria con tus propias conversaciones, no con el ranking de otro.</b></p>
+
+<p align="center"><a href="README.md">English</a> · Español · <a href="https://diegoperezg7.github.io/memarena/">Visor de ejemplo</a></p>
+
+memarena convierte tu exportación de ChatGPT o Claude en un test de memoria: escribe preguntas con su
+respuesta correcta a partir de tu propio historial (las revisas tú), mete el historial en cada capa de memoria,
+hace cada pregunta y puntúa las respuestas con un juez LLM cuyo prompt está publicado. Cada ejecución incluye
+siempre lo que una capa de memoria tiene que superar: **pegar el historial entero** y **una recuperación simple**
+(BM25 y embeddings).
+
+![Visor de memarena, demo grabada](docs/assets/screenshot-light.png)
+
+## Por qué
+
+Los arneses públicos de memoria los publica cada uno un fabricante de memoria y giran en torno a datasets fijos:
+[supermemoryai/memorybench](https://github.com/supermemoryai/memorybench) (334 estrellas, Supermemory),
+[vectorize-io/agent-memory-benchmark](https://github.com/vectorize-io/agent-memory-benchmark) (163, Vectorize) y
+[mem0ai/memory-benchmarks](https://github.com/mem0ai/memory-benchmarks) (134, Mem0) (estrellas a 3 nov 2026).
+
+Las cifras de los fabricantes no cuadran entre sí. El paper de Mem0 da, en LoCoMo, un 26 % de mejora relativa en
+LLM-as-a-Judge frente a la memoria de OpenAI, y un 91 % menos de latencia p95 y más de un 90 % menos de tokens
+que el contexto completo ([arXiv 2504.19413](https://arxiv.org/abs/2504.19413)). Letta publicó después un 74,0 %
+en LoCoMo con GPT-4o mini para un agente con sistema de ficheros, frente al 68,5 % que Mem0 publicó para sí mismo,
+y añadió «Mem0 did not respond to requests for clarification»
+([blog de Letta, 12 ago 2025](https://www.letta.com/blog/benchmarking-ai-agent-memory)). Zep da un 94,8 % en DMR
+frente al 93,4 % de MemGPT y hasta un 18,5 % más de acierto en LongMemEval
+([arXiv 2501.13956](https://arxiv.org/abs/2501.13956)).
+
+Tenga razón quien la tenga en LoCoMo, nada de eso dice cómo funciona una capa de memoria con **tus**
+conversaciones, con **tu** modelo, frente a la opción barata de pegarlo todo. memarena es neutral, trabaja sobre
+tus exportaciones y pone siempre contexto completo, BM25 y embeddings en la misma tabla.
+
+## Inicio rápido
+
+Demo grabada, sin claves, sin Docker y sin llamadas a modelos (menos de 2 minutos en una máquina limpia con `uv`):
+
+```bash
+uvx --from git+https://github.com/diegoperezg7/memarena@v0.1.2 memarena demo
+```
+
+o desde un clon:
+
+```bash
+git clone https://github.com/diegoperezg7/memarena && cd memarena && uv run memarena demo
+```
+
+![memarena demo in the terminal](docs/assets/demo.gif)
+
+Imprime la tabla de abajo y abre el visor en http://127.0.0.1:8765 (`--no-view` para solo imprimir).
+`uvx memarena` llegará con la publicación en PyPI.
+
+## Ejemplo de salida
+
+Es una **ejecución real grabada** (`memarena run`, 3 nov 2026) que va dentro del paquete y que muestra
+`memarena demo`: 20 preguntas (4 por categoría) de
+[LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned) (MIT), con las sesiones de evidencia
+de las 20 juntas en **un solo** historial de 28 sesiones (~75k tokens), como sería la exportación de un usuario.
+
+| Sistema | Acierto | Una sesión | Varias | Temporal | Actualización | Abstención | Recuperación p50 / p95 | Ingesta | Tokens de prompt / p | Coste |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| **mem0** (memoria) | **75 %** | 50 % | 50 % | 75 % | 100 % | 100 % | 49 / 134 ms | 21,6 min | 611 | 0,174 $ |
+| bm25 (línea base) | 70 % | 75 % | 25 % | 50 % | 100 % | 100 % | 0,9 / 3,9 ms | 0,03 s | 4.180 | 0,008 $ |
+| embeddings (línea base) | 55 % | 50 % | 50 % | 25 % | 50 % | 100 % | 105 / 233 ms | 34 s | 3.537 | 0,007 $ |
+| full-context (línea base) | 50 % | 0 % | 0 % | 75 % | 75 % | 100 % | 0,5 / 1,2 ms | 0 s | 69.297 | 0,139 $ |
+
+Configuración: modelo que responde `mistral/ministral-8b-latest` (el mismo para todos), juez
+`mistral/codestral-latest`, mem0 2.2.1 con `ministral-8b-latest` para extraer hechos, embeddings
+`nomic-embed-text` en Ollama local, 10 elementos por recuperador. Hardware: portátil Apple silicon, 10 CPUs,
+16 GB de RAM; el servidor de Ollama estaba compartido con otros trabajos durante la ejecución, así que las
+latencias de embeddings son pesimistas. 20 preguntas es una muestra pequeña: diferencias de una o dos preguntas
+son ruido.
+
+Lo que enseña esta ejecución pequeña:
+
+- **Pegarlo todo perdió.** Con unos 69k tokens de prompt por pregunta, el modelo de 8B respondió «no lo sé» a todas
+  las preguntas de una y de varias sesiones, que sí respondía a partir de fragmentos recuperados.
+- **mem0 envió alrededor del 1 % del prompt de contexto completo** (611 frente a 69.297 tokens por pregunta) y
+  sacó la nota más alta, pero su ingesta tardó 21,6 minutos y costó 0,17 $ en llamadas al LLM para 165 turnos (una
+  extracción por turno), frente a 0,03 s de BM25.
+- **BM25 quedó a 5 puntos de mem0** casi sin coste. Esa diferencia es una pregunta.
+- **Auditoría del juez.** Revisé a mano las 80 decisiones del juez: 3 falsos positivos, todos en temporal (uno en
+  full-context, otro en bm25 y otro en mem0; por ejemplo, aceptó «hace 1 semana» cuando eran «4 semanas») y ningún
+  falso negativo. Acierto corregido: mem0 70 %, bm25 65 %, embeddings 55 %, full-context 45 %. El orden no cambia.
+  La tabla muestra la salida tal cual del juez.
+- Gasto total de esta ejecución: **0,34 $** (API de Mistral, calculado con los tokens que devolvió).
+
+Cada respuesta, el razonamiento del juez y lo que recuperó cada sistema están en el
+[visor de ejemplo](https://diegoperezg7.github.io/memarena/).
+
+## Úsalo con tu historial
+
+```bash
+# 1. Importa tu exportación (conversations.json de ChatGPT o Claude, el .zip, o JSONL)
+uvx --from git+https://github.com/diegoperezg7/memarena@v0.1.2 memarena import conversations.json --out history.json
+
+# 2. Genera preguntas con respuesta y punteros a la evidencia (quedan como "pending")
+memarena generate history.json --out questions.json            # Ollama local por defecto
+
+# 3. Revísalas: edita, aprueba o rechaza en el visor (se guardan en questions.json)
+memarena view --questions questions.json --history history.json
+
+# 4. Ejecuta el benchmark con las preguntas aprobadas
+memarena run history.json questions.json --systems full-context,bm25,embeddings,mem0
+
+# 5. Mira los resultados o expórtalos como web estática
+memarena view results.json
+memarena export results.json --questions questions.json --out site
+```
+
+mem0, Letta y Supermemory son extras opcionales:
+`uvx --from 'memarena[mem0] @ git+https://github.com/diegoperezg7/memarena@v0.1.2' memarena run ...`
+(o `uv sync --extra mem0` en un clon).
+
+**Privacidad.** Con `--provider ollama` y sistemas locales nada sale de tu máquina. Con un proveedor en la nube,
+Supermemory o Letta Cloud, memarena dice adónde van a ir tus conversaciones y pregunta antes de enviarlas
+(`--yes` se salta la pregunta). Las preguntas generadas hay que revisarlas: sin revisión el test no es fiable, así
+que `run` solo usa las aprobadas salvo que pases `--include-pending`.
+
+## Cómo funciona
+
+```mermaid
+flowchart LR
+  E["Exportación ChatGPT / Claude<br/>o JSONL"] -->|memarena import| H[(history.json)]
+  H -->|memarena generate| Q[(questions.json<br/>pendientes)]
+  Q -->|revisión en el visor| QA[(questions.json<br/>aprobadas)]
+  H --> I{ingesta}
+  I --> FC[contexto completo]
+  I --> BM[BM25]
+  I --> EM[embeddings]
+  I --> M0[mem0]
+  I --> LE[Letta]
+  I --> SM[Supermemory]
+  QA --> RQ{recuperación por pregunta}
+  FC & BM & EM & M0 & LE & SM --> RQ
+  RQ -->|mismo modelo y prompt| A[respuestas]
+  A -->|juez LLM, prompt publicado| R[(results.json)]
+  R --> V[visor / web estática]
+```
+
+- **El mismo modelo responde para todos.** Un sistema solo decide qué contexto llega al modelo, así que las
+  diferencias de acierto vienen de la memoria y no del prompt.
+- **Las preguntas** siguen las categorías de LongMemEval: una sesión, varias sesiones, temporal, actualización
+  de conocimiento y abstención (la respuesta no está en el historial y lo correcto es decir «no lo sé»).
+- **Métricas**: acierto según el juez LLM ([prompt exacto](docs/judge-prompt.md)), latencia de recuperación
+  p50/p95, tiempo de ingesta, tokens de prompt por pregunta y coste, en total y por categoría.
+- **Presupuesto**: `--max-cost` (1 USD por defecto) se comprueba antes de cada llamada de pago; si se superaría,
+  la ejecución para y guarda los resultados parciales. Los modelos locales cuentan como 0.
+
+## Sistemas
+
+| Sistema | Tipo | Dónde corre | Estado en v0.1 |
+|---|---|---|---|
+| `full-context` | línea base | en cualquier sitio | historial entero; si no cabe en `--max-context-tokens`, se queda lo más reciente |
+| `bm25` | línea base | local, sin dependencias | BM25 de Okapi sobre pares de turnos usuario/asistente |
+| `embeddings` | línea base | Ollama o cualquier API de embeddings compatible con OpenAI | búsqueda por coseno sobre pares de turnos |
+| `mem0` | memoria | local (mem0ai 2.2.1 OSS, Qdrant en disco) | probado en vivo (demo grabada); también probado con Ollama |
+| `letta` | memoria | API REST de Letta (letta-client 1.12.1) | **sin probar en vivo**: solo con mocks, ver abajo |
+| `supermemory` | memoria | API de Supermemory (supermemory 5.0.1), necesita `SUPERMEMORY_API_KEY` | **sin probar en vivo**: no había clave, solo con mocks |
+
+Lo que salió al construir los adaptadores:
+
+- **mem0 y OpenRouter.** El cliente compatible con OpenAI de mem0 2.2.1 se pasa a OpenRouter siempre que
+  `OPENROUTER_API_KEY` está en el entorno, ignorando la URL configurada. memarena le oculta esa variable a mem0
+  salvo que hayas elegido OpenRouter, para que tu historial vaya solo adonde dijiste. La telemetría de mem0 se
+  desactiva.
+- **mem0 por defecto.** memarena prueba la instalación por defecto de mem0. Su búsqueda BM25 y la lematización
+  con spaCy necesitan los extras `mem0ai[nlp,extras]`, que la v0.1 no instala, así que mem0 usa solo búsqueda
+  semántica.
+- **Letta.** Desde la 0.34 la imagen Docker `letta/letta` y el paquete `letta` de PyPI traen «Letta Code»; el
+  antiguo servidor REST en Python está retirado (la propia imagen lo dice al arrancarla como antes). El adaptador
+  usa la API REST con `letta-client`, así que necesita Letta Cloud (`LETTA_API_KEY`) o un servidor propio que
+  siga exponiendo `/v1`. Guarda cada turno en la memoria de archivo del agente y busca en ella; no ejecuta el
+  bucle del agente.
+
+## Configuración
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `--provider`, `--model` | `ollama`, `qwen3:4b` | modelo que responde (también lo usa `generate`) |
+| `--judge-provider`, `--judge-model` | el mismo que responde | juez |
+| `--embed-provider`, `--embed-model` | `ollama`, `nomic-embed-text` | línea base de embeddings y embedder de mem0 |
+| `--memory-provider`, `--memory-model` | `ollama`, `qwen3:4b` | LLM dentro de mem0 / Letta |
+| `--systems` | `full-context,bm25,embeddings,mem0` | qué comparar |
+| `--top-k` | 10 | elementos que devuelve cada recuperador |
+| `--max-context-tokens` | 100000 | tope de la línea base de contexto completo |
+| `--max-cost` | 1.0 | presupuesto en USD, comprobado antes de cada llamada de pago |
+| `--price in,out` | tabla interna | precio en USD por millón de tokens del modelo que responde |
+
+Proveedores (un solo cliente compatible con OpenAI, claves solo desde variables de entorno, ver
+[.env.example](.env.example)): `ollama` (`OLLAMA_HOST`, por defecto http://localhost:11434), `openai`
+(`OPENAI_API_KEY`), `openrouter` (`OPENROUTER_API_KEY`), `mistral` (`MISTRAL_API_KEY`). Sistemas opcionales:
+`SUPERMEMORY_API_KEY`, `LETTA_API_KEY`, `LETTA_BASE_URL`. memarena no envía telemetría.
+
+**Ventana de contexto de Ollama.** Ollama sirve los modelos con una ventana pequeña por defecto (4096 tokens para
+`qwen3:4b` aquí) y su endpoint `/v1`, compatible con OpenAI, no deja cambiarla por petición, así que los prompts
+largos se recortan en silencio. Crea una vez una variante con más ventana (comparte los pesos, no ocupa disco) y
+usa esa:
+
+```bash
+printf 'FROM qwen3:4b\nPARAMETER num_ctx 16384\n' > Modelfile && ollama create qwen3:4b-16k -f Modelfile
+memarena run history.json questions.json --model qwen3:4b-16k --memory-model qwen3:4b-16k \
+  --max-context-tokens 12000 --num-ctx 16384
+```
+
+Deja `--max-context-tokens` por debajo de la ventana (con margen para la pregunta y la respuesta) para que la
+línea base de contexto completo recorte de forma visible en los resultados y no en silencio en el servidor, y deja
+`--num-ctx` igual a la ventana de la variante para que las llamadas de mem0 no obliguen a Ollama a recargar el
+modelo. Los modelos locales que razonan, como qwen3, piensan antes de responder y en un portátil van lentos. La
+demo grabada no usó Ollama para el chat: su modelo (`ministral-8b-latest`, ventana de 128k) recibió como mucho
+~69,3k tokens de prompt por pregunta, así que no se recortó nada.
+
+Para reproducir los datos y la ejecución de la demo:
+
+```bash
+curl -LO https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_oracle.json
+memarena longmemeval longmemeval_oracle.json --out-dir lme --per-category 4 --max-chars 16000
+memarena run lme/history.json lme/questions.json --systems full-context,bm25,embeddings,mem0 \
+  --provider mistral --model ministral-8b-latest --judge-model codestral-latest \
+  --memory-provider mistral --memory-model ministral-8b-latest --yes --max-cost 2
+```
+
+## Hoja de ruta
+
+- Más sistemas de memoria: Zep / Graphiti (necesitan Neo4j o FalkorDB), cognee, MemOS.
+- claude-mem queda fuera por ahora: es un plugin de sesiones de Claude Code, no una API para ingerir conversaciones.
+- Modo agente de Letta (que el agente edite su propia memoria mientras lee el historial).
+- mem0 con sus extras `nlp` y `extras` (búsqueda híbrida) como configuración aparte.
+- Repeticiones con intervalos de confianza.
+- LoCoMo no se incluye: su licencia (CC BY-NC 4.0) no es compatible con un paquete MIT.
+
+## Datos de terceros
+
+La demo grabada incluye un subconjunto de 20 preguntas de LongMemEval
+([xiaowu0162/longmemeval-cleaned](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned), código en
+[xiaowu0162/LongMemEval](https://github.com/xiaowu0162/LongMemEval)), con licencia MIT, Copyright (c) 2024 Di Wu.
+Su aviso de licencia va junto a los datos, sin modificar, en
+[`src/memarena/data/demo/LICENSE-LongMemEval.txt`](src/memarena/data/demo/LICENSE-LongMemEval.txt)
+(copiado del repositorio de LongMemEval en el commit `9e0b455`), y se incluye en el wheel y en el sdist.
+
+## Licencia
+
+[MIT](LICENSE) para memarena. Los datos de la demo mantienen su propio aviso MIT (ver Datos de terceros).