Content
# BuildVault
**A persistent memory + cross-session awareness system for [Claude Code](https://claude.com/claude-code).**
Claude Code sessions are amnesiac — close the window and the context is gone. Open two windows and they have no idea the other exists. BuildVault fixes both, using nothing but plain Markdown files and a few small Node hooks.
It does three jobs, kept deliberately separate:
1. **Context recovery** — if a session is lost, a per-project *hub note* holds the current state, so context is restored from disk, not from memory.
2. **Build journal** — an honest, dated, append-only log (devlog + crashouts) — raw source material for build-in-public content.
3. **Cross-session awareness** — a shared "whiteboard" so concurrent sessions can see what each other is doing and leave notes.
No database. No cloud. No app to install. Just Markdown + hooks (and an optional zero-dependency MCP server).
---
## The core rule: stream vs. wiki
Two kinds of writing live here, with **opposite** rules. Don't mix them.
| | Stream (`devlog`, `crashouts`) | Wiki (`decisions`, `Wiki/`) |
| --- | --- | --- |
| When written | In the moment | When understanding settles |
| Edited later? | **No — append-only** | Yes — kept current |
| Tone | Raw, messy, honest | Clean, distilled |
| Why | The raw struggle is the content gold | This is what you'd publish or hand off |
The stream *feeds* the wiki: you crash out today, distill the lesson into `decisions.md` next week. Both feed your content.
---
## Layout
```
BuildVault/
Home.md index of all projects + their state
Projects/<name>/
_<name>.md HUB: current state ("where was I")
decisions.md ADR log (evergreen)
devlog.md dated journey (stream, append-only)
crashouts.md failures, raw (stream, append-only)
Wiki/ cross-project evergreen knowledge
Content/ post ideas + drafts mined from the streams
_templates/ copy these to start a project
_scripts/ auto-capture hook
_sessions/ cross-session whiteboard + hooks + MCP server
```
---
## Three pieces of automation
### 1. Auto-capture (`_scripts/devlog-autocapture.js`)
A `SessionEnd` hook. When a session ends inside a tracked project, it appends a single dated breadcrumb to that project's `devlog.md` — turn count, opening request, last request. Zero effort; never overwrites past entries.
### 2. Cross-session awareness (`_sessions/`)
A shared whiteboard (`board.json`) that every session reads and writes:
- **`hook-register.js`** (SessionStart) — registers the session *and* injects "other active sessions" into the new session's context, so it greets you knowing what else is running.
- **`hook-heartbeat.js`** (Stop) — bumps "last seen" and records the current task each turn.
- **`hook-end.js`** (SessionEnd) — marks the session finished.
- **`mcp-server.js`** — an optional dependency-free MCP server exposing the same board as on-demand tools (`sessions_active`, `messages_list`, `message_post`, `message_resolve`).
A session is "active" only if seen within the last 30 minutes, so a crashed session expires instead of haunting the board forever.
### 3. devlog → post (`skills/devlog-to-post/`)
A Claude Code skill that reads a date range of devlog + crashouts and drafts a thread/post/blog into `Content/drafts/` — read-only on the stream.
> **Design note:** Claude Code sessions are turn-based, not always-on. Awareness happens when a session *starts* or *acts* — it can't interrupt another session mid-thought in real time. That covers the vast majority of "don't collide / suggest help" cases.
---
## Install
See **[docs/INSTALL.md](docs/INSTALL.md)** — copy the folder, wire three hooks into `settings.json`, and (optionally) register the MCP server with one command.
---
## License
MIT — see [LICENSE](LICENSE).
