skills/insforge-cli/references/memory.md

# Agent Memory

Every InsForge project has built-in agent memory: a platform-managed store of durable facts, decisions, and gotchas that survive across sessions. It exists to solve the forgetting problem - the next session (or another agent) should not have to rediscover what this one already learned.

## Commands

```bash
npx @insforge/cli memory list                  # title index of stored memories (cheap - no AI call)
npx @insforge/cli memory recall "<query>"      # semantic + keyword recall; --scope, --limit, --threshold
npx @insforge/cli memory remember "<content>"  # store a memory; --kind, --title, --scope, --source
npx @insforge/cli memory remember --file <f>   # extract durable memories from a transcript/notes file
```

All commands honor `--json`.

## The workflow

**At the start of every non-trivial task** - check what past sessions already learned:

```bash
npx @insforge/cli memory list
```

This is cheap (no LLM or embedding call). Scan the titles; if any look relevant, recall the details before designing or debugging:

```bash
npx @insforge/cli memory recall "how are snippet tags filtered"
```

**When you make a decision, hit a gotcha, or change something** - record it at the moment it happens, not at the end of the session:

```bash
npx @insforge/cli memory remember \
  --kind decision --title "Tags as text[] not join table" \
  "Snippet tags are a text[] column with a GIN index, not a join table. Chosen because tags are free-form per owner with no shared vocabulary; revisit if tag analytics are needed."
```

## Kinds

| Kind | Use for | Example title |
|------|---------|---------------|
| `fact` | How something is | "Webhook retries are capped at 3" |
| `decision` | What was chosen and **why** | "Tags as text[] not join table" |
| `preference` | How the user wants things done | "Migrations only, never raw DDL in prod" |
| `reference` | Where something lives | "Stripe staging secret location" |

## What to store

- Decisions **with their rationale** - the "why" exists nowhere in the code and is the highest-value recall.
- Non-obvious gotchas and behaviors you had to discover (cascade semantics, insert-format quirks, which key to use where).
- Where secrets, dashboards, and external resources live.
- Reversals: "we changed X to Y after Z" - memory keeps the current truth plus the history of why it changed.

Write one atomic memory per fact. A well-titled, self-contained sentence or two recalls far better than a paragraph of mixed notes.

## What NOT to store

- Anything derivable from the code or schema itself (recall returns nothing useful that `db tables` wouldn't).
- Transient task state - a failing test you are about to fix, scratch values, in-progress TODOs.
- Things the user merely asked about. Store what is true about the project, not what was discussed.

Memory is for what the next session cannot reconstruct.

## Behavior notes

- **Idempotent by design**: re-remembering a known fact reconciles to a no-op; a contradicting fact updates the existing memory in place (no duplicates). When the truth changes, just `remember` the new truth.
- **Transcript mode** (`--file`): the server extracts only durable facts and skips transient chatter; you do not need to pre-clean the file.
- **Scopes** (`--scope`): memories are partitioned logically (default project scope). Use a scope per agent or per feature area when memories should not cross-contaminate, e.g. `--scope build:snippet-vault`.
- **Empty recall is a feature**: if nothing relevant is stored, recall returns nothing rather than a forced low-confidence match. Do not lower `--threshold` to make results appear.