[sunilp]

Summary (UPDATED scope)

Comprehensive README rewrite framed around OSS adoption and contribution. The earlier scope of this PR was a small post-GA polish (drop alpha banner, rename Status → Roadmap); after a deeper review I rewrote the whole file. Both commits will squash-merge to one entry on main per project convention.

What changed (vs current main)

Dropped:

• The "Phase 1 through Phase 13" feature list. Internal development milestones leak through; they mean nothing to a reader cloning the repo.
• The "v0.1.0a — Phase 1 of the Python rewrite is shipping" banner.
• The "Status" section's Week-N targets (post-launch and stale).
• Loose code blocks scattered through Quickstart that didn't all run as written.

Added or rewritten:

• Hook: working 7-line code example in the first 30 lines (verified to run and produce the documented output).
• Why Engram?: 6 concrete differentiators (mode-aware reading, multi-tenant by default, local-first OR cloud, active fact versioning, benchmarked, MCP-native). Names competitors (Mem0, Letta, Zep, AgentMemory) so the positioning is explicit.
• 60-second tour: 5 small examples — record/recall, build context for an LLM, per-category routing, HTTP server, MCP server. Each is something a developer would copy-paste.
• Core concepts table: Scope, Fact, Engram, Reader, RuleBasedClassifier, MemoryTier, Tool registry — what each is and why a user cares.
• Architecture: one paragraph + ASCII diagram. Names the files where exploration starts.
• Benchmarks section: kept (it was good); added an honest "what we tried, what worked, what didn't" paragraph that surfaces negative results.
• Contributing section: explicit table of "where contributions are most welcome" with difficulty ratings (Easy / Medium / Hard) — embeddings/LLMs/tools as easy onramps, predicate recall and Postgres as medium, "move LongMemEval ≥80%" as hard but high-impact. Plus a "what makes a good PR here" subsection and a "how decisions get made" subsection that links the brainstorm/spec/plan flow.
• Roadmap: prioritized list, each item paired with an invitation ("if any of these are interesting, open an issue").
• Project meta footer: license, security, changelog, Rust runtime pointer, examples, architecture deep-dive (forthcoming).

Net diff

• README.md: 273 lines deleted, 322 lines added (rewrite of 79% of the file)

Test plan

• Headline code example runs and produces the documented output (verified)
• All linked files exist (LICENSE, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, docs/quickstart.md, examples/05_preference_synthesis.py)
• No Phase-N references remain
• No "v0.1.0a" or "when 0.1.0 ships" stale references
• All section anchors used in cross-links resolve

Why one PR not three

The earlier polish commit (075f05a) and the rewrite commit (6cacae2) are both about post-GA README hygiene. Splitting into separate PRs would just delay the broader rewrite from landing. They squash-merge together cleanly.

Summary by CodeRabbit

• Documentation
  • Complete README overhaul with new top banner, intro narrative, and "Why Engram"
  • Added usage example, 60-second tour (record/recall, context-building, per-category routing)
  • New Install section noting Python 3.12 requirement and per-server deployment guides (HTTP, MCP)
  • Expanded Core concepts, public API overview, architecture diagram, benchmarks, production guidance, and roadmap; removed legacy Rust-era content

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: 95cdd1eb-1b9a-46ef-8327-17aaa57daa15

📥 Commits

Reviewing files that changed from the base of the PR and between 075f05a and 6cacae2.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

The README.md was extensively rewritten and expanded into a Python-first, user-facing product document. Additions include a top banner and badges, a usage example, Install (Python 3.12+) instructions, a 60‑second tour, core concepts, architecture and benchmarks, per-server deployment guides (HTTP and MCP), and Contributing/Roadmap/Project meta; legacy Rust-era content removed. No code or public API declarations changed.

Changes

README rewrite and reorganization

Layer / File(s)	Summary
Top banner & badges README.md	New tagline, CI/Python/MIT/PyPI badges and v0.1.0-style header inserted.
Quick usage & summary README.md	Added usage code sample demonstrating Engram.open, memory.record, memory.recall and a short descriptive paragraph.
Motivation / Why Engram README.md	Inserted a "Why Engram?" section outlining core bets (multi-tenancy, local-first/cloud, versioning, benchmarking, MCP tooling, performance).
Install & requirements README.md	New Install section with Python 3.12+ requirement and install commands.
60‑second tour & run guides README.md	Added detailed 60‑second tour (record/recall, context-building, per-category routing) and run examples for HTTP server and MCP server with endpoint/curl snippets.
Core concepts & public API surface README.md	New Core concepts section defining Scope, Fact, Engram, Reader, RuleBasedClassifier, MemoryTier, Tool/ToolRegistry, and import surface.
Architecture & diagram README.md	Inserted architecture overview describing Engram facade, stores (SqliteStore, HnswVectorStore), HybridRetriever, plus diagram.
Benchmarks & production notes README.md	Added Benchmarks (LongMemEval-S results), tooling notes, determinism/embedding/provider tradeoffs, and production guidance.
Contributing / Roadmap / Project meta README.md	Expanded contributing guide, roadmap items, license/security/changelog/project meta; removed older Rust-era and legacy sections.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I nibble lines and craft a guide,
A banner bold, where features bide.
Examples hop, the tour delights,
Benchmarks hum through sleepless nights.
Read on, dear friend — the docs take flight.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

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