feat: redesign README with benchmarks, competitor comparison, agent grid

[rohitg00]

Summary

Major README redesign based on competitive analysis of the AI agent memory landscape (mem0, Letta, Hippo, claude-mem, mnemory).

What changed

Added (high-impact sections):

• Prominent benchmark table — LongMemEval 95.2% R@5 and token savings side-by-side in a two-column layout
• Competitor comparison table — agentmemory vs mem0 (53K stars) vs Letta/MemGPT (22K stars) vs built-in CLAUDE.md across 10 dimensions
• Visual agent grid — all 16 supported agents in a clean 8-column grid layout
• Stats row — 6 key numbers at a glance (95.2% R@5, 92% fewer tokens, 43 tools, 12 hooks, 0 deps, 646 tests)
• 4-tier consolidation table explaining the brain-inspired memory pipeline
• Token savings estimate in the CLI status command

Removed (verbose internal details):

• 34-row KV scopes table (internal implementation detail)
• 123-function breakdown table (too granular for README)
• Lengthy env var comments and inline code examples
• Full API endpoint table (collapsed into expandable section with key endpoints)
• Full MCP tools table (collapsed into core + extended expandable sections)
• Duplicate memory flow diagrams

Result: ~900 lines → ~540 lines. More visual impact, less scrolling, better first impression.

Why

Research across Reddit (r/ClaudeAI, r/mcp), HN, and web sources shows:

• Developers choose memory tools based on benchmark numbers and competitor comparisons
• "$10/day in wasted tokens" is the universal pain point — benchmark tables make the value proposition instant
• Agent logos/grids create visual credibility (mem0 does this well)
• Long internal details (KV scopes, function lists) hurt more than help for adoption

Test plan

• All 646 tests passing (including README consistency check)
• Verify README renders correctly on GitHub
• Check all internal anchor links work
• Verify tables render on mobile GitHub

Summary by CodeRabbit

Release Notes

• Documentation

  • Reorganized README with new Benchmarks section, token savings comparison, Supported Agents reference, and vs Competitors matrix.
  • Simplified API and Architecture documentation.
  • Updated Quick Start and integration instructions.

• New Features

  • Enhanced status command to display observation counts, memory metrics, and estimated token savings.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request updates the project documentation with new sections (vs Competitors, Supported Agents) and restructured benchmarks/architecture content, while enhancing the CLI status reporting to fetch additional export data and compute token savings metrics.

Changes

Cohort / File(s)	Summary
Documentation README.md	Reorganized navigation; added new sections for competitor comparison and agent integrations; restructured benchmarks with token savings; simplified API and architecture documentation; consolidated and rewrote multiple subsections including memory pipeline, search, and MCP server content.
CLI Status Enhancement src/cli.ts	Extended runStatus() to fetch /agentmemory/export endpoint alongside existing health and stats calls; added computed metrics for observations and memories counts; implemented token savings calculation (~obsCount*80 full vs min(obsCount,50)*38 injected) with percentage reduction output.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• feat: DX improvements — dark mode, status command, memory previews #102: Adds the initial runStatus() command with health/sessions/graph fetches; this PR extends it with export data and token savings metrics.
• docs: README polish — badges, cost table, architecture diagram #106: Contains overlapping README documentation changes to navigation anchors and benchmarks/costs sections.

Poem

🐰 A doc refresh and metrics so fine,
New sections align, benchmarks redesign,
Export data flows, token savings we know,
Status shines bright with computed insight—hooray!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary changes: README redesign with three main additions (benchmarks, competitor comparison, agent grid). It is concise, specific, and directly reflects the changeset's focus.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/readme-redesign-benchmarks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}