grandma

Your AI forgets everything between sessions. Every morning you re-explain your stack, your conventions, your client, your life. Grandma fixes that. She gives Claude Code a persistent memory that is yours (plain markdown in your own git repo), separated by sweater (one per part of your life, kept apart), and learned passively while you work.

A sweater is a context you keep separate memory in — one company, one client, your job hunt, your writing. Open a sweater and grandma remembers everything about that part of your life and nothing from the others. Your projects live inside a sweater.

Grandma does three things a single session never can:

• Keeps your worlds apart. Client A's memory never shows up in a client B session — enforced by a test, not by discipline.
• Remembers across all of them, forever. Tell her once, in any session; every future session in that sweater knows.
• Analyzes your whole history and acts on it. She can study weeks of your chats and turn what she finds into memory:

$ grandma "analyse my last 2 weeks of chats, write how I actually write, and make it part of my identity"
grandma> read 1,297 of your messages across 19 sessions.
         ✓ wrote global/style.md (3 registers: how you type, how your work should read, how you write prompts)
         ✓ updated global/identity.md
         review it: git -C ~/.grandma diff

Here is the everyday loop. Teach her once, and a brand new session already knows:

# Monday
$ grandma acme
you> we use pnpm here, never yarn. and never push to main directly.
grandma> ✓ noted (preference) -> acme/facts.md: pnpm only, no direct pushes to main
         ...continues your actual task...

# Thursday, brand new session
$ grandma acme
grandma> ▣ memory: acme loaded · 4 files · ~1.9k tokens
you> set up the new billing service
grandma> Scaffolding with pnpm. I'll open a PR rather than pushing to main.

Watch it happen:

Install

curl -fsSL https://raw.githubusercontent.com/anshulforyou/grandma/master/install.sh | bash

That clones the engine, creates your private memory home, and offers a two-minute interview where grandma learns who you are. Or manually:

git clone https://github.com/anshulforyou/grandma && cd grandma && ./bin/grandma init

Requirements: Claude Code, git, jq, python3. macOS or Linux (Windows via WSL). grandma doctor checks everything and tells you how to fix what is missing.

Update

The engine is a git checkout, so updating is a fast-forward:

grandma update          # land on the latest master, then show what changed
grandma update --force  # same, but stash local engine edits first
grandma version         # what you are running right now

Update always lands you on master, whichever branch the engine checkout is on, and it only ever fast-forwards: no force, no rewritten history. If you have been hacking on the engine, uncommitted changes to tracked files stop it with a list of what it found, and --force stashes those for you and prints the command to get them back. Untracked scratch files are left where they are. It also stops rather than guess when the situation is ambiguous: a local master with commits of its own, a branch another worktree has checked out, a detached HEAD holding work nothing points at, or an engine directory that turns out to be inside some other git repository.

grandma tracks master (a rolling release). It never phones home: instead of checking a server, it prints one quiet line at launch when your engine has gone stale (more than a week since your last grandma update), nudging you to run it. Silence that with GRANDMA_NO_UPDATE_CHECK=1, or tune the window with GRANDMA_UPDATE_STALE_DAYS. Re-running the installer updates in place too.

Tab completion

Optional, and worth it. With it on, grandma <TAB> lists your sweaters, grandma per<TAB> completes the one you mean, and grandma acme <TAB> lists the projects under acme. Add one line to your shell rc:

# bash: add to ~/.bashrc
eval "$(grandma completions bash)"

# zsh: add to ~/.zshrc, below an existing `autoload -Uz compinit && compinit`
eval "$(grandma completions zsh)"

# fish: add to ~/.config/fish/config.fish
grandma completions fish | source
# (or persist it once: grandma completions fish > ~/.config/fish/completions/grandma.fish)

Start a new shell and press TAB after grandma. Grandma does not touch your rc file for you, so turning this on stays your call.

Search your memory

Sometimes you just want to know what she remembers, without starting a session:

$ grandma search pnpm
global/preferences.md:9:- pnpm only, never yarn
acme/facts.md:4:- pnpm workspaces, one lockfile at the root
  2 match(es) in 2 file(s)

$ grandma search acme migrations       # scoped to one sweater
acme/facts.md:6:- Postgres, migrations via atlas only
  1 match(es) in 1 file(s) · sweater acme

Read-only, and it never starts Claude. Output is file:line:text, so it pipes like grep. The scoped form searches that sweater alone (not global), so a hit always tells you which sweater owns the memory. Matching is a case-insensitive literal string — ripgrep when you have it, grep otherwise, and both are made to agree. Exit codes follow grep: 0 matches, 1 no matches, 2 bad usage. Pending proposals and watch scratch are not searched; they are not memory until you accept them.

How it works

Three layers of memory, loaded in the right amounts at the right times:

global/             who you are, how you like to work        always loaded
<sweater>/            one folder per context: a job, a client, loaded for that sweater only
                    a side project, your job hunt
project CLAUDE.md   deep per-project instructions            auto-loaded in that folder

• grandma acme assembles global + acme memory and launches Claude Code with it.
• grandma acme billing-api also drops you into that project so its CLAUDE.md rides along.
• grandma alone shows a picker, including "describe a new sweater" where you explain a new context in plain words and grandma scaffolds it.

Memory lives in GRANDMA_HOME (default ~/.grandma), a git repo that belongs to you. The engine never stores your data next to its own code.

She learns while you work

During a session, when something worth keeping comes up (a preference, a correction, a fact that changed, a lesson), grandma writes it to the right memory file and tells you in one line:

✓ noted (correction) -> global/preferences.md: never auto-commit, review diffs first

Writes land as uncommitted diffs in your memory repo. git diff is your review queue. Nothing is committed behind your back.

She survives the context window

Long sessions hit Claude Code's compaction, which normally drops the instructions grandma injected at launch. Two hooks cover this. The moment compaction happens, grandma re-injects your memory, so hour six behaves like minute one. And just before compaction, it checkpoints the working state of the current task (what you decided, what is done, what is next) and folds that back in too, so the session keeps the thread of its own work and not just your standing preferences. When you exit, grandma looks over the session right then and shows you what she noted, the live diffs plus a drafted proposal, and asks whether to review now or leave it. Nothing is applied without you. (Sessions you did not start with grandma get the same distill quietly in the background, surfaced at your next launch.)

She watches for your blind spots

grandma watch start "why are my sessions getting longer?" --weeks 2

For two weeks grandma measures every session (duration, turns, tokens, compactions, tool calls) and reads the substantial ones. When the window closes you get a notification and a grounded report: the patterns, the numbers, what to change. It found real bugs in its own development. It will find your habits too.

Day to day

Eight recipes with real transcripts in docs/use-cases.md:

1. Stop re-explaining your stack every session
2. The correction that sticks forever
3. Client A and client B, with contexts that cannot bleed
4. Onboard a new project in five minutes
5. Survive a marathon session
6. End the day, review what she learned
7. Find out why your sessions drag
8. Grandma is not just for work

Why files, why git

Trust

• 16 tested invariants guard the core promise: loading sweater X injects exactly global + X and nothing else, only a real sweater can be loaded at all, the engine contains no sweater jargon and no personal data, no secrets in memory, hooks cannot recurse or r