chore: import upstream snapshot with attribution

docs/benchmarks/2026-05-20-coding-agent-life-v1.md

@@ -0,0 +1,101 @@
+# 2026-05-20 — coding-agent-life-v1 (v0.9.26)
+
+**Bench:** coding-agent-life-v1 (15 sessions, 15 queries)
+**N:** 15
+**K:** 5
+**Hardware:** macOS 15 (Apple Silicon)
+**agentmemory:** v0.9.26
+**iii-engine:** v0.11.2
+**Embedding provider:** local default
+**Sandbox:** isolated data dir at `/tmp/agentmemory-eval-sandbox/`, ports 3411/3412
+
+## Math ceiling on this dataset
+
+12 of 15 questions have 1 gold session, 3 have 2 gold sessions. Per
+`scoreQuestion` in `eval/runner/score.ts`, P@K = `hits / k` averaged
+across questions, so the **maximum achievable P@5** is:
+
+```
+(12 * 1/5) + (3 * 2/5)) / 15 = (2.4 + 1.2) / 15 = 0.240
+```
+
+R@5 ceiling is **1.000** (every gold session found in top-5).
+
+The benchmark is **small** (15 questions) and **gold-sparse** (mostly
+single-gold). It's tuned for fast iteration on the retrieval stack,
+not for headline P@K comparisons. **Recall** + per-question-type
+**P@5** are the signals; aggregate P@5 saturates at 0.240 so it can't
+differentiate top-tier adapters.
+
+## Headline
+
+`agentmemory-hybrid` hits **100% top-5 hit rate**, R@5 = **1.000**,
+P@5 = **0.240** (at the math ceiling — every gold session retrieved
+in top-5).
+
+grep baseline: R@5 = **0.967**, P@5 = **0.227** — missed one gold
+session in one multi-gold question. Lift is **recall**, not aggregate
+precision.
+
+## Per-adapter
+
+| Adapter | P@5 | R@5 | Hit rate | p50 latency |
+|---|---|---|---|---|
+| grep (tokenized substring) | 0.227 | 0.967 | 15 / 15 | 0 ms |
+| `agentmemory-hybrid` | **0.240** | **1.000** | **15 / 15** | 14 ms |
+
+`agentmemory-hybrid` runs through the production smart-search endpoint (`POST /agentmemory/smart-search`) so it exercises the full BM25 + embedding + reranker stack.
+
+## Per-question-type
+
+At K=5 with 1 gold per single-session question, the P@5 ceiling per
+question is **0.20**; with 2 gold the ceiling is **0.40**. Both
+adapters saturate the per-type ceiling on most types, so the per-type
+table primarily exposes where one adapter **misses** gold (failing
+the recall side).
+
+| Type | grep P@5 | grep R@5 | hybrid P@5 | hybrid R@5 |
+|---|---|---|---|---|
+| single-session-bug | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-infra (n=2) | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-refactor | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-feature | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-test | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-perf | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-api | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-db | 0.20 | 1.00 | 0.20 | 1.00 |
+| single-session-release | 0.20 | 1.00 | 0.20 | 1.00 |
+| multi-session-causal (2 gold) | 0.40 | 1.00 | 0.40 | 1.00 |
+| preference (n=2) | 0.20 | 1.00 | 0.20 | 1.00 |
+| multi-session-review (2 gold) | 0.40 | 1.00 | 0.40 | 1.00 |
+| temporal (2 gold) | 0.20 | 0.50 | 0.40 | 1.00 |
+
+The differentiator at this corpus size is **temporal** (`What was shipped on April 8th 2026?`): grep finds 1 of 2 gold sessions, hybrid finds both. Per-type R@5 saturates everywhere else.
+
+## Methodology
+
+- 15 fictional Claude Code sessions across a 10-day stretch of a Rust CLI project (`shipctl`) — bug fixes, refactors, infra, perf, schema migrations, preferences, post-mortem
+- 15 hand-graded queries with `goldSessionIds[]` covering single-session, multi-session causal, multi-session review, preference, temporal
+- Each session ingested via `POST /agentmemory/remember` with `type=eval-session` and `concepts=[session_id]`
+- Each query hits `POST /agentmemory/smart-search` with `limit=50`; dedupe by session ID; truncate to K=5
+- No LLM in the retrieval loop
+- Sandbox: clean `~/.agentmemory` via `HOME` override + alt ports (3411/3412) so no cross-contamination from a user's real store
+
+## Reproduce
+
+```sh
+git checkout e9dc710
+npm install --legacy-peer-deps
+npm run build
+
+source eval/scripts/sandbox.sh
+npm run eval:coding-life -- --adapters grep,agentmemory
+```
+
+Outputs land in `eval/reports/coding-life/`: `scores.ndjson` (per-query rows) and `summary.json` (per-adapter and per-type aggregates).
+
+## Notes
+
+- The single-session-feature tie (`Which PR introduced helm chart support?`) is interesting: query says `PR introduced helm chart` and gold session has `helm chart` literally — grep wins on lexical exactness, hybrid matches but doesn't outperform.
+- The corpus is intentionally small for fast iteration. Hardening targets: paraphrased queries, synonym substitution, in-corpus distractors with shared keywords, longer multi-session chains.
+- Vector adapter not measured here — requires `OPENAI_API_KEY`; will be added in a follow-up scorecard alongside LongMemEval `_s`.

docs/benchmarks/TEMPLATE.md

@@ -0,0 +1,54 @@
+# <YYYY-MM-DD> — <benchmark-name>
+
+**Commit:** `<sha>`
+**Bench:** LongMemEval `_s` / coding-agent-life-v1 / ...
+**N:** 500 / 15 / ...
+**K:** 5
+**Hardware:** macos-15 / ubuntu-22.04 / ...
+**OpenAI model:** text-embedding-3-small
+**Anthropic model:** N/A (no LLM in retrieval loop)
+
+## Headline
+
+agentmemory-hybrid: **R@5 = XX.XX%**, P@5 = XX.XX%, p50 latency = XXms
+
+Beats grep baseline by +X.Xpt R@5, vector by +X.Xpt R@5.
+
+## Per-adapter
+
+| Adapter | P@5 | R@5 | Hit rate | p50 latency |
+|---|---|---|---|---|
+| grep | | | | |
+| vector | | | | |
+| agentmemory-hybrid | | | | |
+
+## Per-question-type
+
+| Type | grep R@5 | vector R@5 | agentmemory R@5 |
+|---|---|---|---|
+| single-session-bug | | | |
+| single-session-refactor | | | |
+| preference | | | |
+| multi-session-causal | | | |
+| temporal | | | |
+
+## Methodology
+
+- Sessions ingested via `POST /agentmemory/remember` with `type=eval-session`
+- Queries hit `POST /agentmemory/smart-search` with `limit=k*4`
+- No LLM in retrieval loop. Direct rank from hybrid scoring.
+- Ranks dedup by sessionId before truncating to K
+- Latency measured as init+query for LongMemEval (per-question fresh state), query-only for coding-life (shared state)
+
+## Reproduce
+
+```sh
+git checkout <sha>
+npm install --legacy-peer-deps
+OPENAI_API_KEY=sk-... AGENTMEMORY_BASE_URL=http://localhost:3111 \
+  npm run eval:longmemeval -- --stratify 10
+```
+
+## Notes
+
+<what surprised, what regressed, what's load-bearing>

docs/recipes/pairings.md

@@ -0,0 +1,119 @@
+# Pairings
+
+Open-source projects shipping the rest of the AI coding agent context layer. agentmemory ships persistent session memory. The projects below ship code-graph indexing, multi-agent build pipelines with dashboards, and broader knowledge graphs across non-code assets. Stack them and your agent gets a fuller picture in fewer tool calls.
+
+## [codegraph](https://github.com/colbymchenry/codegraph) — pre-indexed code knowledge graph (MCP)
+
+What it does: builds a SQLite-backed code knowledge graph (symbols, call edges, route handlers, full-text search) and exposes it through an MCP server with 8 tools (`codegraph_search`, `codegraph_context`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_node`, `codegraph_status`, `codegraph_files`). File watcher keeps the index fresh. Their published benchmark (across VS Code, Django, Tokio, OkHttp, Gin, Alamofire, Excalidraw) shows agents finishing the same architecture question in **~35% less cost, ~70% fewer tool calls** when codegraph is wired in.
+
+Recipe with agentmemory — both as MCP servers on the same agent:
+
+```jsonc
+// ~/.claude.json or your agent's MCP config
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    },
+    "agentmemory": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@agentmemory/mcp"]
+    }
+  }
+}
+```
+
+Question routing that falls out:
+
+| Question | Tool the agent reaches for |
+|---|---|
+| "What does `shipctl helm install` call?" | `codegraph_callees` |
+| "Where is `auth_check` defined?" | `codegraph_node` |
+| "Which routes hit the user controller?" | `codegraph_callers` on the controller node |
+| "What did we decide last week about retries?" | `memory_smart_search` |
+| "Why did we pick async-std?" | `memory_recall` |
+| "Fix the auth bug from the post-mortem" | `memory_smart_search` → post-mortem session, then `codegraph_node` → current `auth.rs` |
+
+## [Understand Anything](https://github.com/Lum1104/Understand-Anything) — multi-agent code-graph pipeline + dashboard
+
+What it does: a Claude Code plugin (also installable on 13+ other agents) runs a multi-agent pipeline over a project and produces an interactive web dashboard at `understand-anything.com`. Architecture layers, business-flow domain view, guided tours, persona-adaptive UI, diff impact analysis, framework-aware routes across 14 frameworks. The graph commits to `.understand-anything/knowledge-graph.json` so teammates skip the pipeline.
+
+Slash commands:
+- `/understand` — build the graph (incremental on re-run)
+- `/understand-dashboard` — open the interactive web dashboard
+- `/understand-chat` — ask anything about the codebase
+- `/understand-diff` — analyze impact of current changes
+- `/understand-explain` — deep-dive a file or function
+- `/understand-onboard` — generate an onboarding guide
+- `/understand-domain` — extract business domains, flows, steps
+- `/understand-knowledge` — analyze an LLM wiki knowledge base
+
+Recipe with agentmemory:
+
+```bash
+# Day 1 — new team member joins
+/understand                                     # builds the graph
+/understand-dashboard                           # opens the visual map
+/understand-onboard                             # generates onboarding guide
+
+# Week 2 — same engineer hits a bug
+/understand-explain src/auth.rs                 # architecture context
+# agentmemory MCP surfaces the post-mortem and the past 3 fixes touching auth.rs
+```
+
+The graph teaches you the codebase. agentmemory remembers what you and the agent already did inside it. The two planes don't overlap.
+
+## [Graphify](https://github.com/safishamsi/graphify) — broader knowledge graph across code, docs, PDFs, images, videos
+
+What it does: a single slash command (`/graphify .`) maps a whole project — application code, SQL schemas, R scripts, shell scripts, docs, PDFs, papers, images, videos — into one queryable knowledge graph. Output is three files: an interactive `graph.html`, a markdown `GRAPH_REPORT.md` with highlights and suggested questions, and the full `graph.json`. Also ships `graphify export callflow-html` for Mermaid call-flow architecture pages.
+
+Runs as a skill on Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Copilot CLI, VS Code Copilot Chat, Aider, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, and Google Antigravity.
+
+Recipe with agentmemory:
+
+```bash
+/graphify .                                     # one graph: code + docs + PDFs + images
+```
+
+This is the broadest sweep across artifacts that live alongside the code. agentmemory then captures everything the agent does while exploring that graph — the questions you asked, the conclusions, the decisions — so the next session opens with both the graph and the conversation history available.
+
+## How the four projects line up
+
+Four planes, four consumers, four update models. None of them try to do what the others do.
+
+| Project | Plane | Surface | Consumer | Update model |
+|---|---|---|---|---|
+| [agentmemory](https://github.com/rohitg00/agentmemory) | session history (observations, decisions, preferences) | MCP + REST + hooks | agent | live (observations stream) |
+| [codegraph](https://github.com/colbymchenry/codegraph) | code structure (symbols, call edges, routes) | MCP server | agent | live (FS watcher) |
+| [Understand Anything](https://github.com/Lum1104/Understand-Anything) | code structure + business domain + architecture | plugin (slash commands) + web dashboard | **human** + agent | on-demand `/understand` |
+| [Graphify](https://github.com/safishamsi/graphify) | code + docs + PDFs + images + videos | skill (slash command) | human + agent | on-demand `/graphify` |
+
+## Question types each project handles best
+
+| Question shape | Best tool |
+|---|---|
+| "What's the architecture of this repo?" | Understand-Anything dashboard or Graphify `graph.html` |
+| "Where is symbol X defined? Who calls it?" | codegraph (`codegraph_node`, `codegraph_callers`) |
+| "What does this PDF spec say about the rate limit?" | Graphify |
+| "Why did we pick X over Y three sessions ago?" | agentmemory (`memory_smart_search`) |
+| "What did we ship on April 8?" | agentmemory (`memory_timeline`) |
+| "How does the payment flow work in this codebase?" | Understand-Anything (`/understand-chat`) |
+| "Trace impact of changing `Foo::bar`" | codegraph (`codegraph_impact`) or Understand-Anything (`/understand-diff`) |
+| "What preferences has the team locked in?" | agentmemory |
+
+## Suggested install order for a brand-new project
+
+1. **agentmemory** — observe and persist from day one, even before the codebase has structure. Run `npx @agentmemory/agentmemory connect` and pick your agent.
+2. **codegraph** — once code lands, agent queries answer from the index instead of grepping. Run `npx @colbymchenry/codegraph`.
+3. **Understand Anything** *or* **Graphify** — when the codebase passes a few thousand LOC or starts shipping docs and PDFs alongside code, generate the graph for visual exploration and onboarding. Run `/plugin install understand-anything` or `uv tool install graphifyy && graphify install`.
+
+All four are local-first (no data leaves the machine for code-graph workloads). Stacking them costs nothing extra at the network boundary.
+
+## Cross-project benchmark idea
+
+`eval/runner/adapters/` accepts new adapters against the same coding-agent-life-v1 corpus and the published LongMemEval `_s` benchmark. A `codegraph` adapter or an `understand-anything` adapter or a `graphify` adapter would let us publish a side-by-side scorecard showing which project owns which question class. The win for the ecosystem is precise framing: each project gets credit for what it does best, with reproducible numbers from a shared harness.
+
+If you build any of those adapters, open a PR against `agentmemory` with the adapter file under `eval/runner/adapters/` and a scorecard under `docs/benchmarks/`. The scaffold and contract live in [`eval/README.md`](../../eval/README.md).