Second brain

The context repo is the difference between an assistant that knows the user and one that asks the same three questions every session. It is plain markdown in git, not a database, and that is deliberate: the user can read it, correct it, and see its history.

Your job is to keep it true and to use it before guessing.

Layout

setup.sh creates five flat files, which is the right starting shape:

YOU.md      identity, background, how they work
NOW.md      current roles, active projects, priorities, what is broken
PEOPLE.md   collaborators, family, professional network
SYSTEM.md   hooks, commands, MCP, infrastructure
STACK.md    tech stack and standards

YOU.md and NOW.md are the two the session hook loads, so keep them tight. NOW.md is the most useful file and the one most likely to be stale.

Once a repo outgrows five files, the shape that scales is directories by volatility: a small always-loaded core/, then domains/, projects/, and systems/ read on demand, plus memory/ for granular one-fact-per-file notes indexed by a MEMORY.md. Do not impose that on someone with five files.

Reading

Grep before you ask. grep -ri "<term>" <context-repo> is the fast path and it beats asking a question the repo already answers. Being asked something you were told three weeks ago is the failure this system exists to prevent.

Read the specific file, not the whole repo. If the user mentions a project, read that project's file. Loading everything is slow and crowds out the actual work.

Check NOW.md first for anything time-sensitive. It goes stale fastest, so verify it against what the user just said rather than trusting it blindly.

Writing

Update it as work happens, in the same turn, without being asked and without announcing it. A new role, a project shipping or dying, a collaborator joining, a preference stated, something breaking or getting fixed: write it to the right file while it is true, not at the end of the session when it has been forgotten.

Five rules, each of which exists because its absence rots the repo:

One fact, one home. Before adding anything, grep for it. If it already exists, update that file. Duplicated facts are how these systems die: five copies in five directories, all disagreeing, all stale, none authoritative.

Volatility decides the file. Stable facts (identity, values) go in files reviewed rarely. Volatile facts (current work, priorities) go in NOW.md. A volatile fact in a stable file is how an identity file ends up lying about what semester it is.

Absolute dates only. "Last week" is meaningless to a session six months from now. Every dated claim gets YYYY-MM-DD.

Mark what you are unsure of. A question mark on a carried-over claim is worth more than false confidence. A future reader needs to know what was verified and what was inherited.

If the user contradicts the repo, the user is right. Fix the file in the same turn. Never argue with someone using their own stale notes.

What does not belong

• Anything derivable from a codebase: structure, git history, past fixes
• Anything that only matters inside one conversation
• Secrets. Those live in a password manager or environment variables, never here

If asked to remember something in one of those categories, ask what was non-obvious about it and save that instead. "We fixed the auth bug" is in git. "Auth breaks whenever the staging env var drifts, and it has happened three times" is worth keeping.

Granular memory

memory/ holds one fact per file with frontmatter naming its type: user, feedback, project, or reference. feedback and project entries carry a Why and a How to apply, because a rule without a reason gets misapplied. Link related entries so the store becomes a graph rather than a pile.

Every new memory file gets a one-line pointer in MEMORY.md immediately. MEMORY.md is the index that gets loaded; a memory missing from it is a memory that will not be found.

Auditing

When asked to review the context repo, check for:

• Facts that contradict each other across files
• Anything in an always-loaded file that should have aged out into an on-demand one
• Relative dates that were never converted
• Projects listed as active that have not been touched in months
• Duplicates, which mean the one-fact-one-home rule slipped

Report what you found and fix the mechanical problems directly. Ask before deleting anything that looks like judgment rather than rot.