# Quickstart: Your Assistant's First Memory (free)

> **Human:** open your AI CLI assistant (Claude Code, Codex CLI, or any
> agentic assistant that can read files and run commands), point it at this
> file, and say: **"Read this file and set me up."** Then answer its
> questions. In about twenty minutes your assistant will know something true
> about your life and remember it across sessions. This piece is free and
> stands alone; it is the first of the "Build Your Own AI OS" course.

## Assistant briefing

You are giving your user the one thing every AI chat lacks: durable memory
they own. You will build a tiny git-tracked folder of plain markdown (the
vault), wire it so it loads at the start of every session (the kernel), and
write one real canonical doc so a brand-new session can answer a question
about your user's life from the file, with dates, without being re-told.
Work conversationally: interview first, build, then verify.

**Ground rules:**
- Interview before building. One question at a time.
- Never write secrets (API keys, tokens, passwords) into any file. This
  quickstart needs none.
- Ask permission before writing outside the folder the user chooses.
- If a step fails, stop and show the user the actual error. Never fake a
  passing check.

## Step 0: Interview

Ask the user, one at a time (skip any already answered):

1. What OS are you on, and is git installed? (`git --version` if unsure.)
2. Where should the vault live? `~/Context` is a fine default.
3. Name one real topic from your life right now that you are tired of
   re-explaining: a project you are shipping, a decision you keep
   revisiting, anything with a current state. For it, ask: what is the
   current state, the most recent decision (with its date), and the next
   open loop.
4. Which CLI assistant are you using, and does it support a global
   instructions file? (For Claude Code: `~/.claude/CLAUDE.md`, with `@`
   imports.)

## Step 1: Create the vault and put it in git

Why: plain markdown in git is portable, auditable, and yours forever. No
vendor memory feature gives you that.

```bash
mkdir -p ~/Context && cd ~/Context
git init
# git needs an identity before its first commit; set one if unset, or the
# commit aborts with "Author identity unknown" on a fresh machine.
git config user.email >/dev/null 2>&1 || git config --global user.email "$(whoami)@$(hostname -s).local"
git config user.name  >/dev/null 2>&1 || git config --global user.name  "$(whoami)"
```

Create three files so the first commit is never empty (git does not track
empty folders): `CLAUDE.md` (the rules, next step), `INDEX.md` (a one-line
map of your docs), and the canonical doc in Step 3.

## Step 2: The kernel, so the vault loads every session

Why: one import line makes your assistant read the vault's rules at the
start of every session, from any directory. That single line is the whole
trick.

Write `~/Context/CLAUDE.md`:

```markdown
# Vault rules

## Session boot

This file loads at session start and imports the map:

@~/Context/INDEX.md

## How memory works here

- Every fact, decision, and open loop lives in one canonical markdown file.
- Date-stamp every update: `- [2026-01-01] the thing that changed`.
- Newest items go at the TOP of a section.
- Never delete history; move stale items to an Archive section at the bottom.
```

Then, for Claude Code, make `~/.claude/CLAUDE.md` load the vault. Its entire
contents can be one line:

```
@~/Context/CLAUDE.md
```

Tilde imports work in Claude Code. If your assistant does not expand `~` in
imports, use the resolved absolute path instead. For other assistants, put
the vault's rules file wherever their global instructions live.

## Step 3: Write one real canonical doc

Why: this is the payoff. One honest file about a real topic is what turns a
generic assistant into one that knows your situation.

From the user's answer to interview question 3, create a doc in the vault
(for example `~/Context/my-first-topic.md`) and add its one-line pointer to
`INDEX.md`. Write it in the user's own words, dated:

```markdown
# <the topic>

- [<today's date>] Current state: <where it stands right now>.
- [<the date of the decision>] Decided: <the most recent decision and why>.
- Open loop: <the next thing that has to happen>.
```

Commit everything:

```bash
cd ~/Context && git add -A && git commit -m "vault: first memory"
```

## Ship check

Do this with the user and let them watch:

1. Open a brand-new terminal in a directory that has nothing to do with the
   vault, and start your assistant fresh.
2. The user asks a question whose answer lives only in the doc you just
   wrote: "what is the current state of `<topic>`?" or "what did I decide
   about `<topic>`, and when?"
3. Pass: the assistant answers with the dated specifics from the file,
   without the user re-explaining anything.

That is the whole idea, at its smallest. Your assistant now has a memory you
own, in plain files, that survives every session.

## What you just proved

The rest of the OS is more of this, one piece at a time: a task store so
"what's next" returns one confident answer, senses so your assistant can
read your real calendar and inbox, and rituals so every session ends with
the record updated and committed. Each piece installs exactly the way this
one did: a setup file you hand to your assistant.

The full course is at **johnsaad.com/course**. This piece was on the house.