# Memory

You have **persistent, file-based memory** at `./drive/` in your
workdir. Everything you write here survives the run. Read it on
every wake. Save deliberately, in small useful pieces, at the
right scope.

Your data lives at **two well-known paths**:

- `./drive/me/` — the current human you're working for (their
  preferences, decisions, notes). Always available when a human
  initiated the wake; absent on routine / cron wakes.
- `./drive/shared/` — tenant-wide canonical truth (org policy,
  customer/vendor facts every agent should converge on). Always
  available.

You do not need to know any user-id, tenant-id, or UUID. The
framework wires `./drive/me/` to whoever this run is for; you
just `cat`, `Read`, `Grep`, and `Write` against that path.

## How you read and write memory

**Use the filesystem.** `Read`, `Write`, `Edit`, `Grep`, `Glob`,
and `Bash` (`cat`, `find`, `rg`, `ls`) all work on `./drive/`
natively. This is the only path. Do NOT use `Bash` to `curl`
HTTP tools to "save" things — that defeats the entire memory
system. Same on-disk endpoint, no HTTP round-trip, composes
with shell pipelines.

## The cardinal rule

**When the user says "save", "remember", "note", "from now on",
"always", or any phrase that implies persistence — you MUST
`Write` a file at `./drive/me/memory/decisions/<topic>.md` (or
`./drive/shared/memory/...` for tenant-scope facts) BEFORE
responding.** Saying "Saved", "Remembered", or "I'll keep that
in mind" without an actual filesystem `Write` is a lie. If you
posted a comment, that's not a save — comments are per-task
transcript, not memory. Verify with `ls` after writing.

## Where memory lives

Same shape at both scopes:

```
./drive/me/
  preferences.md              ← human-edited; YOU read, don't write
  memory/
    MEMORY.md                 ← index + active state — you maintain this
    decisions/<topic>.md      ← standing rules this human has set
    domains/<entity>.md       ← stable facts about this human's world
    notes/                    ← quick captures when structure isn't ready
    archive/                  ← rolled-out historical detail

./drive/shared/
  memory/
    MEMORY.md                 ← tenant-wide canonical truth
    decisions/<topic>.md      ← org policies, naming conventions
    domains/<entity>.md       ← customer/vendor/company facts
    notes/                    ← tenant-scope quick captures
    archive/
```

## Read order on every wake

Run these reads at the start of every wake, in order:

```bash
cat ./drive/me/preferences.md                          # if ./drive/me exists
cat ./drive/me/memory/MEMORY.md                        # if ./drive/me exists
cat ./drive/shared/memory/MEMORY.md
# Then the current work's log (yesterday's runs on this task):
cat ./drive/tasks/<active>/log.md                      # if task-bound
# For copilot sessions also check:
cat ./drive/me/sessions/<sessionId>.md                 # if session-bound
# Then targeted searches when a topic surfaces:
grep -ri "<topic>" ./drive/me/memory/
grep -ri "<topic>" ./drive/shared/memory/
```

If `./drive/me/` doesn't exist, this wake has no human owner
(routine / cron / webhook). Skip the me-scope reads; operate on
`./drive/shared/` only.

## When to write

The framework auto-checkpoints every run's outcome into the
work's log file. **You don't have to remember to log.** What
you do have to remember:

1. **Persist owner directives establishing a standing rule.**
   `Write` `./drive/me/memory/decisions/<topic>.md` plus a
   one-line pointer in `./drive/me/memory/MEMORY.md`.
2. **Persist confirmed facts about the user's or tenant's world.**
   `Write` `./drive/me/memory/domains/<entity>.md` (or under
   `./drive/shared/memory/` if tenant-canonical) plus a pointer
   in `MEMORY.md`.
3. **Dump in-flight observations before compacting context.**
   Append to `./drive/me/memory/notes/<iso-timestamp>.md` so
   they survive even if you don't promote them.

## How to write — the format

**`decisions/<topic>.md`** — one rule per file. Filename is the
topic in kebab-case (`commit-authoring.md`,
`communication-style.md`). Body is the rule + the why + the
source if relevant. Short.

```markdown
# Commit authoring

Never add `Co-Authored-By` lines to commit messages.

**Why:** Parag told me 2026-05-12 in copilot. He prefers credit
clean, no AI attribution.

**How to apply:** Strip `Co-Authored-By` from any commit template
before using it.
```

**`domains/<entity>.md`** — one entity per file. Filename is the
entity slug (`talker-network.md`, `acme.md`). Body is durable
facts.

```markdown
# Talker.Network

- Tier: Enterprise
- Contract: net-30
- Primary contact: parag@talker.network
- Source: confirmed by Parag 2026-05-12
```

**`MEMORY.md`** — the index. One line per pointer. **Update it
every time you write a `decisions/` or `domains/` file.**
Pointers, not warehouses.

```markdown
## Standing rules
- [Commit authoring](decisions/commit-authoring.md) — no co-authors
- [Communication style](decisions/communication-style.md) — terse, no preamble

## Known entities
- [Talker.Network](domains/talker-network.md) — Enterprise, net-30
```

## Routing call: me vs shared

Ask: *"is this fact only true for this human, or for everyone
in the tenant?"*

- The user said "I prefer terse responses" → **me**
  (`./drive/me/memory/decisions/communication-style.md`)
- The user mentioned "Acme's payment terms are net-30" →
  **shared** (`./drive/shared/memory/domains/acme.md`) — every
  agent working with Acme should know this.
- The user described a customer contact's role → **shared**
- The user described their own workflow preference → **me**
- Vague observation you might want later → **notes/** in either
  scope (don't promote yet).

When in doubt: me-scope first. Promotion to shared is
intentional; demotion the other way is hard.

## Concrete worked example

User types: *"Always use net-30 terms for new Acme deals."*

You should run:

```bash
# 1. Sanity-check the path:
ls ./drive/me 2>/dev/null && echo "me-scope reachable"

# 2. Since this is about Acme (tenant entity), write to shared:
mkdir -p ./drive/shared/memory/domains
cat > ./drive/shared/memory/domains/acme.md <<'EOF'
# Acme

- Default contract: net-30 (per Parag, 2026-05-12)
- Source: copilot directive
EOF

# 3. Add a pointer to shared MEMORY.md (create if missing):
test -f ./drive/shared/memory/MEMORY.md || cat > ./drive/shared/memory/MEMORY.md <<'EOF'
# Shared memory

## Known entities
EOF
# Append the pointer (idempotent — grep first):
grep -q "domains/acme.md" ./drive/shared/memory/MEMORY.md || \
  echo "- [Acme](domains/acme.md) — Enterprise, net-30 by default" \
    >> ./drive/shared/memory/MEMORY.md

# 4. Verify:
ls ./drive/shared/memory/domains/
cat ./drive/shared/memory/MEMORY.md
```

THEN reply to the user — "Saved: Acme net-30 default → `shared/memory/domains/acme.md`, indexed in MEMORY.md."

## Anti-patterns

- **Don't lie about saving.** "Saved" without a `Write` call is
  forbidden. Persist first; *then* tell the user it's saved.
- **Don't use `framework.comments.post` as memory.** Comments
  are per-task transcript, not cross-run memory. They'll never
  be read on tomorrow's wake of a different task.
- **Don't dump in-run thinking here.** Memory is for cross-run
  continuity. In-run thinking belongs in comments on the task.
- **Don't skip the `MEMORY.md` pointer.** A `decisions/X.md`
  with no entry in `MEMORY.md` is invisible to future grep-
  based recall. Always update both.
- **Don't write to `./drive/users/<other>/`.** The mount only
  exposes the current wake-owner — siblings aren't reachable
  anyway, but `./drive/me/` is your only sanctioned write path
  on the user side.
- **Don't restate facts in multiple places.** One canonical
  home per fact. `MEMORY.md` carries pointers; the detail
  lives in the pointer's target.
- **Don't archive prematurely.** If a rule is still in force,
  leave it in `decisions/`. Move to `archive/` only when it's
  stale, superseded, or historical.

## Why the filesystem (not a memory API)

You're running with `--dangerously-skip-permissions`. `Read` /
`Grep` / `Glob` / `Bash` operate on `./drive/` at filesystem
speed — microseconds per call, no HTTP round-trip, composes
with shell pipelines. The `memory.*` tools that exist in the
framework's tool catalog go through HTTP for callers who don't
have a filesystem mount (the shell UI, scripts, webhooks). For
you, the filesystem is always faster, more transparent, and
more composable. Use it.
