diff --git a/.brain/context/current-state.md b/.brain/context/current-state.md index c2e7ada..088fc25 100644 --- a/.brain/context/current-state.md +++ b/.brain/context/current-state.md @@ -1,5 +1,5 @@ --- -updated: "2026-04-12T04:31:58Z" +updated: "2026-04-12T05:22:46Z" --- # Current State @@ -77,3 +77,4 @@ Add repo-specific notes here. `brain context refresh` preserves content outside - 2026-04-11: Returned the local checkout to `main` after PR #3 merged and fast-forwarded the repo to `v0.1.5`, which includes the wrapper cleanup, Windows session-lock fix, and corrected reusable release input handling. - 2026-04-11: Repositioned the product docs around Brain as durable local operating memory for AI coding agents. The README now leads with the continuity/reliability story, keeps install + skill install + brainstorm-to-execution prominent, treats lower token and tool cost as supporting proof, and replaces the bottom link dump with high-level overview sections that deep-link into usage, architecture, skills, and why. - 2026-04-11: Tightened the Windows session-lock fix again after PR feedback. Lock acquisition now treats Windows `os.ErrPermission` during lock-directory races as retryable contention even if a follow-up stat misses the directory, which should stop intermittent `Access is denied` failures in concurrent session tests. +- 2026-04-11: Tightened the README positioning pass by adding an explicit audience section for heavy AI-agent users, a `Why Brain Exists` founder-pain section, and a cleaner deep-dive section structure so the README sells urgency before dropping into technical overviews. diff --git a/README.md b/README.md index 5cc8715..8a29eca 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,17 @@ That usually means: `brain` fixes that by making the project itself the memory system. +## Who This Is For + +`brain` is for developers who already use AI coding agents heavily and are tired of paying the context tax every session. + +It fits best when: + +- you use an AI agent regularly on a real, evolving codebase +- you are tired of repeating the same architecture and product context +- you want planning, docs, retrieval, and workflow to live with the code +- you want the project to stay understandable to humans too, not just the agent + ## What Brain Actually Does `brain` keeps human docs at the repo root, machine-managed state under `.brain/`, and a local SQLite search index for durable project knowledge. @@ -196,6 +207,12 @@ brain brainstorm start --project . "Initial ideas" brain search --project . "architecture" ``` +## Why Brain Exists + +`brain` exists because most AI agent pain is not raw coding ability. It is continuity failure. + +Agents can write code quickly, but they lose project context, drift on decisions, forget why work was scoped a certain way, and burn money re-learning the same repo over and over. Brain exists to keep that continuity local, durable, and usable by both the agent and the human team. + ## Why This Saves Time And Money `brain` cuts waste in two places: @@ -205,7 +222,7 @@ brain search --project . "architecture" You still need good prompts and good engineering judgment. But when the agent can work against a stable local brain, you spend less money and fewer turns just rebuilding context. -## How Brain Works +## Explore Brain In More Detail ### How Brain Works