docs(readme): redraft for first-time discoverer (190 → 162 lines) - #508
Merged
Conversation
The 'Persistent memory for AI agents' line is the generic part — every
memory project (Letta, Mem0, Zep, MemGPT) says some version of the same
thing. The differentiated bits ('Set up once / Stays out of your way')
were already strong; replace only the weak first sentence with one that
names the actual user-visible outcome.
Three short H2s in a row (Determinism, Your data stays yours) read choppy and bury the framing. Collapse into one section that opens with 'Running in the background. No action required after aelf setup.' — the actual benefit framing. Dropped: explicit fastmcp dep disclosure (covered by pyproject.toml), 'No GPU, no vector DB' bullet (subsumed by 'no embeddings'). Per-project isolation folded into Local-only as a corollary.
The reproducibility badge at the top of the file already advertises the bench harness and links to docs/v2_reproducibility_harness.md. The prose section was landing-page space spent on docs content — issue numbers, schema versions, cron-branch names — none of which a first-time discoverer needs to decide whether to install. The badge stays. The detail doc stays. Only the README prose is cut.
The 13-row roadmap table was wall-of-issue-numbers — #232, #148, #280, #321, etc. — and inside-baseball theme summaries that rewarded contributors but punished first-time discoverers. The full per-version detail already lives at docs/ROADMAP.md and was already linked from the trailer line. Replace with a 7-line Status section: latest shipped version (v1.7, named features), next planned (v2.0, theme), and links out to docs/ROADMAP.md + docs/LIMITATIONS.md for everyone who needs more. No issue numbers in landing copy.
Four atomic docs commits redrafting README for first-time-discoverer audience. Cut from 190 → 162 lines (-28). Tagline rewrite, three-section merge, reproducibility prose dropped, full roadmap table → 7-line Status. Verification: - Line count: 162 (was 190); 4 atomic commits + this gate - Diff stat: +12 / -40, single file (README.md) - All H2 anchors still resolve to existing doc links (PHILOSOPHY.md, PRIVACY.md, ROADMAP.md, LIMITATIONS.md, COMMANDS.md, MCP.md, SLASH_COMMANDS.md) — no broken internal references introduced - Hero image, badges, install snippet, "What it does" example block, "Why files don't solve this" comparison, "Day-to-day surface", Documentation index, Citation block all unchanged - Tagline: Option B (pain-forward) per user pick - Branch: docs/readme-discoverer-rewrite, branched from current HEAD (clean off recent main) Blockers (require user decision before next phase): - [user] Approve diff and authorize push to github remote, OR - [user] Request adjustments to any of the four atomic commits before push - [user] Confirm whether to open PR vs merge-locally on main Open questions: - Tagline keeps "Auditable" out of subline-3 (per literal Option B pitch). Adding it back is a 1-line amendment if preferred. - "What it remembers" table (lock/onboard/feedback rows) was kept as separate H2 since it's API surface, not abstract benefit. Confirm this is the intended split. Rollback: - git reset --hard main (drops all 4 docs commits + this gate; branch is local-only, never pushed)
Original tagline had three anchors (Local SQLite, Auditable, No GPU/no network). Earlier rewrite dropped 'Auditable' to match the literal Option B pitch; restoring it because it names a real differentiator vs. embedding-based memory systems that the body alone doesn't adequately surface in 30-second-skim mode.
Reviewer's guide (collapsed on small PRs)Reviewer's GuideREADME.md has been redrafted to better target first-time discoverers by tightening copy, merging overlapping sections, and simplifying roadmap/status information while preserving technical accuracy and key links. Flow diagram for new README section structureflowchart TD
A[What_it_does] --> B[What_it_remembers]
B --> C[Why_files_dont_solve_this]
C --> D[What_you_get_for_free]
D --> E[Day_to_day_surface]
E --> F[Status]
F --> G[Documentation]
G --> H[Citation]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughREADME hero tagline updated from "Persistent memory for AI agents." to "Your AI stops forgetting your rules." Feature sections consolidated: "Determinism" and "Your data stays yours" merged into "What you get for free"; "Reproducibility" and "Roadmap" condensed to "Status" with version information and resource links. ChangesREADME Documentation Refresh
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The new tagline "Your AI stops forgetting your rules" is quite absolute; consider softening or qualifying it (e.g., "keeps your rules stable" or "helps your AI stop forgetting your rules") so it better matches realistic behavior and edge cases.
- In the "What you get for free" list, the determinism bullet now compresses a lot of technical nuance into one sentence; consider splitting it into two short bullets (mechanics vs. implication) to keep it scannable for first-time readers while preserving precision.
- The hardcoded "Latest stable: v1.7" / "Next: v2.0" in the Status section will drift over time; consider either linking directly to GitHub Releases or explicitly labeling these as examples tied to the last README update date to reduce future maintenance overhead.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new tagline "Your AI stops forgetting your rules" is quite absolute; consider softening or qualifying it (e.g., "keeps your rules stable" or "helps your AI stop forgetting your rules") so it better matches realistic behavior and edge cases.
- In the "What you get for free" list, the determinism bullet now compresses a lot of technical nuance into one sentence; consider splitting it into two short bullets (mechanics vs. implication) to keep it scannable for first-time readers while preserving precision.
- The hardcoded "Latest stable: v1.7" / "Next: v2.0" in the Status section will drift over time; consider either linking directly to GitHub Releases or explicitly labeling these as examples tied to the last README update date to reduce future maintenance overhead.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 103: Update the sentence that currently reads "No action required after
`aelf setup`" to a softened phrase that reflects the first-run onboarding steps;
replace that exact string with something like "No recurring action required
after setup/onboarding" or "No recurring action required after `aelf setup`
(initial onboarding like `aelf onboard .` or `aelf lock ...` may still be
needed)" so the README no longer implies absolute no further steps while
preserving the intended meaning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ## What you get for free | ||
|
|
||
| Same store + same query gives the same beliefs. The retrieval path is stdlib + SQLite — no embeddings, no learned re-rankers, no LLM — so every result traces back to a specific belief and the user action that wrote it. | ||
| Running in the background. No action required after `aelf setup`. |
There was a problem hiding this comment.
Line 103 overstates “no action required” after setup.
“No action required after aelf setup” conflicts with nearby first-run flow (aelf onboard ., optional aelf lock ...). Consider softening to “no recurring action required after setup/onboarding.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 103, Update the sentence that currently reads "No action
required after `aelf setup`" to a softened phrase that reflects the first-run
onboarding steps; replace that exact string with something like "No recurring
action required after setup/onboarding" or "No recurring action required after
`aelf setup` (initial onboarding like `aelf onboard .` or `aelf lock ...` may
still be needed)" so the README no longer implies absolute no further steps
while preserving the intended meaning.
robotrocketscience
added
the
attn:review
Owner
Author
|
[claim:review:Kulili:2026-05-09T05:26:41Z] |
Owner
Author
|
[release:review:Kulili:2026-05-09T05:27:57Z] |
This was referenced May 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Net: 190 → 162 lines, +12/-40, single file. Optimized for first-time-discoverer audience per audience-pick during drafting.
H2 structure now: What it does → What it remembers → Why files don't solve this → What you get for free → Day-to-day surface → Status → Documentation → Citation.
Six atomic commits + one gate commit. No content changes outside README.md.
Test plan
<aelfrice-memory>example block still render correctlySummary by Sourcery
Redraft the README to better orient first-time users and streamline status information without changing core functionality.
Documentation:
Summary by CodeRabbit