memcellar

See it run · Quickstart · How it works · Commands · Skill packs · Coming from Second Brain OS · Architecture

memcellar is a memory for Claude Code and Codex that lives in plain files. It is an Obsidian vault and a Git repository at once. Your agent knows who you are and what you are working on from the first message of a session. Before it answers, it reads its own index and cites the page the answer came from. What it learns lands as Markdown you can open, edit and commit. Git is the only database: git log is the audit trail, git revert is undo.

See it run

You ask a question about your stack. The agent reads its own INDEX.md, opens the page it points to, and answers with that page as its source, so you can check it and correct it where it is wrong.

Why

• A session starts from what you already told it. Who you are, how you like to work and the facts that matter are loaded at every start. The rest is looked up, through INDEX.md, when a question needs it.
• Answers come with their source. The agent cites the page it read, so you can check it, and correct it where it is wrong.
• Memory that stays tidy. Every page is typed by how long it stays true. A short write gate runs before anything is saved, so a new fact updates the page it belongs to instead of piling up as notes-v2.
• Nothing to run or keep in sync. No database, no vector store, no server, no build step: just Markdown, JSON and Node, on Windows, macOS and Linux.
• Projects keep their own memory. Each project's status lives in its own repo, committed with the code. The vault stays out of it.

This is a cleaned-up copy of a vault I have used every day since 2026-08-18, with the personal content taken out. Everything here runs somewhere, and what was tried and removed is listed as removed — see docs/DECISIONS.md. Every choice in that vault got a numbered decision record (ADR), the reversed ones included, which is why the numbers run high; v1.0, v1.1 and v2 are snapshots of the same vault. Full records ship from ADR 0045 on; 0001–0044 are one line each in the index.

How it works

• One hook, and it never commits. Both runtimes run the same SessionStart hook. Inside the vault it pulls and injects core/. Once a day it may also say which upkeep pass has work waiting; it asks, it never runs one. Outside the vault it does nothing.

• Reading is a rule. Before answering anything the vault may already know, the agent reads INDEX.md and the pages it points at. It then greps notes/, reports/ and core/ in the language you asked in, and cites the page. logs/ comes last.

• You talk, the agent distills. Something worth keeping is written on the spot. Before any page is written, the agent runs the write gate (.agents/write-gate.md):

  1. it writes nothing if the fact is already written down;
  2. it picks the page's type;
  3. it lists the pages on the same subject (scripts/note-neighbours.mjs);
  4. in the same commit, it closes the pages the new one makes stale.

  What you dictate word for word becomes an owner page (author:), which no agent pass rewrites.

• Your language, your browser. The vault talks and writes in the language you chose at setup. In Obsidian, notes/home.md links the topic hubs and your to-do page, and archive/, logs/ and raw/ stay out of search and the graph.

• Commits belong to the task. Each task commits the files it wrote, by name — never git add -A — so two sessions, or both runtimes, can share one checkout.

• One copy of everything. AGENTS.md is the only rulebook (CLAUDE.md just imports it) and .agents/skills/ the only skills folder, for Claude Code and Codex alike.

A page's type says how long it stays true (ADR 0055):

One subject has one topic page. A report or a deliverable adds a line and a link to its topic page, so INDEX.md lists only the living layer. Tiers, budgets and the reasoning behind each part are in docs/ARCHITECTURE.md.

Three homes, and projects stay walled off

Your memory lives in three places, and each session loads only the ones it needs (ADR 0056):

• the vault — what you know, think and decide; read in vault sessions;
• each project's repo — that project's state, decisions and lessons; read only in that project;
• your kit — your user-level instruction file and two folders beside it: how you want work done, carried into every session, in the vault and in every project.

A session in a project neither reads nor writes the vault. The hook does nothing there, and the project keeps its own state, decisions and lessons.

To see every project at once, run node scripts/project-doctor.mjs --board from the vault. It prints one row per repo, read live: the last commit, the active milestone and the state file's Next line. It writes nothing.

What the kit is. Your user-level instruction file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) plus two folders next to it, lessons/ and reference/. You don't create it: the first time /lesson or /closeout saves something, the folder appears. To keep it in a git repo of its own, point BRAIN_KIT_DIR at that folder. Keep it private: lessons quote you word for word.

The kit is the only home that crosses projects: a correction you give in one repo is there when you open the next. It fills only if /lesson and /closeout run in your projects, so link them once with node install.mjs --link-global-skills. Without that, they run in the vault alone and the kit stays empty.

A choice made in one project, such as its framework, stays in that project's docs/decisions/; another project is free to choose differently. From the vault you can still ask about any project: the session reads its repo live, read-only, and copies nothing back.

Formats and adoption steps: .claude/templates/project-repo/. The decisions: ADR 0045, ADR 0052.

core/         loaded at every session start ("Tier 0"): IDENTITY, USER,
              MEMORY inlined; OPEN_QUESTIONS by pointer
notes/        the living layer — topic pages, decisions, playbooks, project
              cards, and your own pages (author:); flat, wikilinked, told
              apart by frontmatter; home.md is the front page
reports/      dated research and comparisons, written once
outputs/      lists, drafts and other deliverables, each with an expiry date
raw/          immutable sources you put there; the agent reads, never writes
logs/         append-only session logs + logs/signals/, the event ledger
archive/      closed and superseded content — never deleted, always moved here
scripts/      link sweep, neighbour finder, vault and project doctors,
              maintenance, metrics
.agents/      skills, the optional skill packs and the write gate — the one
              copy both runtimes load
.claude/      the shared SessionStart hook, the compiled checks, page and
              project-repo templates
.codex/       the thin Codex adapter into that same hook
AGENTS.md     the constitution — the rules you and both agents work under
CLAUDE.md     one line that imports AGENTS.md, plus Claude-only notes
INDEX.md      the page catalog — read this first when answering a question
PROPOSALS.md  open work you keep by hand; no pass writes to it
SETUP.md      agent-run installation runbook, with a manual appendix
install.mjs   one-time interactive personalization, skill links and packs
docs/         architecture, decisions, FAQ, upgrade guide, the README's figures

Quickstart

You need:

• git 2.28+ and Node.js 18.13+;
• a GitHub account, with the GitHub CLI (gh, logged in): the agent-run setup creates your repo with it;
• Claude Code or Codex, or both.

Obsidian is optional; the vault is plain Markdown either way.

1. Hand the setup to your agent. Open Claude Code or Codex and paste:

   Read SETUP.md from this repository and set up my memcellar vault:
   https://github.com/brkakyldz/memcellar/blob/main/SETUP.md
   

2. Answer its questions. It creates your private repo from this template, interviews you, personalizes the core files, links the skills and checks that the hook fires. It asks before creating the repo and before writing user-level settings.

3. Check the wiring: node scripts/vault-doctor.mjs.

4. Work normally. Talk to your agent inside the vault: plan a project, think a problem through, ask what you decided last month. When a piece of work is done, it commits exactly the files that work touched.

Prefer to do it by hand? Manual setup runs node install.mjs. It interviews you and prints the wiring without touching your user-level settings or committing anything.

Wiring, in short.

• Claude Code needs nothing beyond this repo's own .claude/settings.json.
• Codex gets core/ once its SessionStart entry is wired in ~/.codex/hooks.json. Don't also add one in a project-level .codex/hooks.json: Codex adds the layers together. Details: SETUP.md, Step 5.
• Link /closeout and /lesson into your projects: node install.mjs --link-global-skills (--unlink-global-skills undoes it). This is what fills your kit: without it, nothing learned in one project reaches the next. They write into the project or your kit, never into the vault.

Everyday commands

Scripts you run when you want them — nothing runs on a schedule:

• node scripts/maintenance.mjs: what upkeep is due; run does the mechanical half after your yes.
• node scripts/vault-doctor.mjs: is the setup healthy.
• node scripts/project-doctor.mjs: is each project's memory committed and its state fresh; --board gives one row per project.
• node scripts/note-neighbours.mjs "<subject>": the pages already on a subject.
• node scripts/link-sweep.mjs: broken links and orphans.
• node .claude/hooks/checks.mjs --staged: run before a commit.

All of them: scripts/README.md.

Skill packs

Four optional packs of skills for project work live in .agents/packs/. They load nowhere until you link one at user level. After that, its skills work in every project and in the vault (ADR 0062).

node install.mjs --list-packs shows them, --pack <name> links one and --unpack <name> removes exactly those links.

Coming from Second Brain OS

memcellar v2 is the next release of Second Brain OS, which was last published as v1.1. Its headline: every page is typed by how long it stays true, projects and the vault are walled off, and the search machinery is gone.

• Reading. The agent reads INDEX.md and the pages it points at, then greps. /recall, the ranker and its eval are retired.
• Writing.
  • The topic, report and deliverable page types replace knowledge and memory, with the new reports/ and outputs/ folders.
  • A write gate runs before every write, with a neighbour finder.
  • New checks catch pages of the wrong type, expired deliverables and -v2 pages.
• Projects.
  • The hook does nothing outside the vault: no pull, no injection. Global mode is gone.
  • The vault's three homes: the repo, your kit and the vault.
  • project-doctor --board shows every project.
  • docs/WORKLOG.md is retired; git log is a project's history.
• Lessons. One file per recurring behaviour, in your kit by default. The second correction on the same behaviour proposes a rule.
• Upkeep. A once-a-day "Maintenance due" line, computed from outstanding work. Nothing runs until you say yes.
• Your own pages and language. Pages you write yourself sit in notes/ with an author: field, and a check keeps the agent from rewriting them. The vau