> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Graph and memory

> Commands that write to and read from the graph: recording notes and decisions, searching them back, reading the change log, and the maintenance operations that rewrite the graph itself.

This is where the things you want remembered go in, and where they come back out. `base learn` and `base decision log` write; `base recall` and `base decision search` read. `base changes` is the append-only log of every successful write. `base graph` is the maintenance layer underneath all of it, plus the natural-language and node-walking retrieval built on top.

<Warning>
  Four commands on this page remove data: `base decision delete`, `base memory purge`, `base graph purge` and `base graph compact`. `base graph move` rewrites two graphs. Read each one's note before you run it, and use the preview where there is one.
</Warning>

## base learn

Store a note in the graph, linked to a domain and optionally to a project or an entity. This is the general-purpose write: an insight, a correction, a commitment, a change of direction.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base learn --text "Mint dev serves on 3111 by convention here" --domain basemode --type insight
base learn --text "The docs deploy is a push to main" --domain basemode --type decision --project basemode
base learn --list
base learn --list --domain basemode
base learn --update mint-dev-port --text "Mint dev serves on 3111"
base learn --remove mint-dev-port
base learn --mention mint-dev-port --context "came up again while writing the reference"
base learn -g --text "Prefer relative paths in prose" --domain writing
```

| Flag                  | Short | What it does                                                                                    |
| --------------------- | ----- | ----------------------------------------------------------------------------------------------- |
| `--text <TEXT>`       |       | The note itself. Required unless you are using `--mention`, `--remove`, `--update` or `--list`. |
| `--type <TYPE>`       |       | `insight`, `correction`, `decision`, `commitment` or `shift`. Defaults to `insight`.            |
| `--domain <DOMAIN>`   |       | The domain to link to. Required unless you are using `--mention`.                               |
| `--project <PROJECT>` |       | Link the note to a project as well.                                                             |
| `--entity <ENTITY>`   |       | Link the note to an entity as well.                                                             |
| `--mention <MENTION>` |       | Record that an existing note came up again. Takes the note's slug.                              |
| `--context <CONTEXT>` |       | The circumstance of the mention.                                                                |
| `--remove <REMOVE>`   |       | Remove a note by slug.                                                                          |
| `--update <UPDATE>`   |       | Update a note's text by slug. Needs `--text` as well.                                           |
| `--list`              |       | List stored notes. Filter with `--type` or `--domain`.                                          |
| `--global`            | `-g`  | Write to the global tier instead of this workspace.                                             |

`--mention` is the one people miss. It records that a note came up again, incrementing its mention count and stamping when it last happened, which is useful for spotting the things you keep running into.

It does **not** protect a note from `base graph purge --stale`. That reads `lastRead`, and only an explicit `base recall` writes it. Verified from source at `4866996`.

## base recall

Search stored notes by text, by domain, or by exact slug.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base recall --keyword "mint"
base recall --domain basemode
base recall --slug mint-dev-port
```

| Flag                  | What it does                      |
| --------------------- | --------------------------------- |
| `--keyword <KEYWORD>` | Search the text of stored notes.  |
| `--domain <DOMAIN>`   | Only notes linked to this domain. |
| `--slug <SLUG>`       | Look one note up directly.        |

Run this before assuming something was never written down. It searches notes only, and decisions have their own search.

<Note>
  `base recall` writes, despite being a search. It stamps `lastRead` on every note it returns, and that timestamp is the one `base graph purge --stale` measures against. So recalling a note protects it from the next purge. Injection during a turn does not do this: only the explicit command writes, deliberately, so the hot path never pays for a graph write.
</Note>

## Decisions

A decision is a note with a reason attached and a stable address. It is the right shape for anything you will be asked to justify later.

`base decision` carries `-g` / `--global` on the command itself, before the verb. `base d` is the short alias.

### base decision log

Record a decision and the reasoning behind it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base decision log --domain basemode --decision "Docs live at docs.basemode.ai" --rationale "Subdomain keeps the marketing site and the manual separately deployable"
base decision log --domain basemode --decision "Docs live at docs.basemode.ai" --rationale "Separately deployable" --recall "where do the docs live"
```

| Flag                      | What it does                                    |
| ------------------------- | ----------------------------------------------- |
| `--domain <DOMAIN>`       | The domain this decision belongs to. Required.  |
| `--decision <DECISION>`   | What was decided. Required.                     |
| `--rationale <RATIONALE>` | Why. Required.                                  |
| `--recall <RECALL>`       | Extra text to help this decision surface later. |

The rationale is not optional, and that is deliberate. A decision without its reasoning cannot be revisited, only obeyed or ignored.

### base decision search

Find prior decisions by keyword, with their reasoning.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base decision search --keyword "docs"
base decision search --keyword "docs" --json
```

| Flag                  | What it does                                        |
| --------------------- | --------------------------------------------------- |
| `--keyword <KEYWORD>` | Matched against decision names. Required.           |
| `--json`              | Emit JSON on a stable contract, instead of a table. |

### base decision update

Change a decision in place, addressed by its slug.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base decision update basemode.docs-live-at-docs-basemode-ai --rationale "Subdomain keeps deploys independent"
base decision update basemode.docs-live-at-docs-basemode-ai --status superseded
```

| Flag                      | Short | What it does             |
| ------------------------- | ----- | ------------------------ |
| `--name <NAME>`           |       | Rename the decision.     |
| `--rationale <RATIONALE>` |       | Replace the reasoning.   |
| `--recall <RECALL>`       |       | Replace the recall text. |
| `--status <STATUS>`       | `-s`  | Set the status.          |

The argument is the `{domain}.{decision}` slug, or the exact decision text. Updating in place is almost always better than deleting and re-logging: it keeps the address, and the edges pointing at it.

### base decision delete

**Destructive, no preview.** Delete every decision matching a keyword.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base decision delete --keyword "docs"
```

| Flag                  | What it does                              |
| --------------------- | ----------------------------------------- |
| `--keyword <KEYWORD>` | Matched against decision names. Required. |

There is no dry-run. Run `base decision search --keyword "docs"` first and read what comes back, because that is the set this will remove.

## base changes

Read the change log: every successful graph write, as JSON.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base changes --cursor
base changes --since 48210
base changes -g --cursor
```

| Flag              | Short | What it does                                            |
| ----------------- | ----- | ------------------------------------------------------- |
| `--since <SINCE>` |       | Print entries written after this offset.                |
| `--cursor`        |       | Print the current end offset and exit.                  |
| `--global`        | `-g`  | Read the global tier's log instead of this workspace's. |

The cursor is a **byte offset into the log**, not a sequence number. That is why it needs no separate counter, survives several writers appending at once, and is the exact value a reader resumes from: take the cursor, do your work, then ask for everything since.

## Graph maintenance and retrieval

`base graph` is the layer under the graph itself. The maintenance verbs are atomic and take a snapshot before they write. Never hand-edit `graph.nq`.

### base graph compact

**Destructive.** Deduplicate and canonicalize the workspace graph, as a single atomic rewrite. It snapshots first.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph compact
```

There is no preview. The snapshot is the safety net, and a snapshot you have not checked is not a plan, so know why you are compacting before you do.

### base graph purge

**Destructive. Preview by default.** Remove notes that have gone unread past a threshold.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph purge --stale
base graph purge --stale --days 60
base graph purge --stale --days 60 --apply
```

| Flag            | What it does                                                                     |
| --------------- | -------------------------------------------------------------------------------- |
| `--stale`       | Required. Selects the stale-note rule, which is the only purge rule that exists. |
| `--days <DAYS>` | The unread-age threshold. Defaults to 21.                                        |
| `--apply`       | Actually delete. Without it you get a dry-run preview and nothing changes.       |

The clock is recency only: a note's age resets every time it is recalled. So this removes what you have not needed, not what is old.

### base graph move

**Destructive. Preview by default.** Move a subgraph from one registered workspace's graph to another. It rewrites the stamp that says which graph a node belongs to, backs up both tiers, and rolls back if anything fails.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph move --select "domain:basemode" --to basemode
base graph move --select "prefix:docs-" --to basemode --from chris-ai-systems --dry-run
base graph move --select "domain:basemode" --to basemode --no-ast --yes
```

| Flag                | What it does                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `--select <SELECT>` | What to move: `node:<iri>`, `domain:<name>`, `prefix:<str>`, or a full node IRI. Required. |
| `--to <TO>`         | Destination workspace name, as registered in `base.toml`. Required.                        |
| `--from <FROM>`     | Source workspace name. Defaults to the one you are in.                                     |
| `--dry-run`         | Print the plan and write nothing.                                                          |
| `--no-ast`          | Leave code-map entities behind and regenerate them at the destination.                     |
| `--yes`             | Apply the move. Without it, you get the plan and nothing else.                             |

`--no-ast` is usually what you want when the destination will be synced anyway: code entities regenerate from source in seconds, and moving them carries stale paths across.

### base graph apply-ops

Apply inbound fact operations, read as JSON on standard input. This is the receiving half of syncing a graph from somewhere else.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph apply-ops < ops.json
base graph apply-ops --global < ops.json
```

| Flag       | What it does                                          |
| ---------- | ----------------------------------------------------- |
| `--global` | Apply into the global tier instead of this workspace. |

It accepts either a bare array of operations or an object with an `ops` key, applies every assert and retire in one transaction, and prints how many were applied, skipped as duplicates, and skipped as unknown. If any operation is invalid it exits nonzero having applied none of them, so a partial write is not a state you can end up in.

### base graph extract

Run a language-model pass over a corpus of documents and write the concepts and edges it finds into the graph.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph extract --target docs/
base graph extract --target docs/ --model haiku
base graph extract --target research/ --multimodal
```

| Flag                | Short | What it does                                                            |
| ------------------- | ----- | ----------------------------------------------------------------------- |
| `--target <TARGET>` | `-t`  | The directory to extract. Defaults to the one you are in.               |
| `--model <MODEL>`   | `-m`  | Which model alias to extract with, such as `haiku`, `sonnet` or `opus`. |
| `--multimodal`      |       | Force multimodal ingest for this run.                                   |

Markdown only, by default. PDF, image, audio and video need multimodal enabled, either permanently with `base config set multimodal.enabled true` or for one run with `--multimodal`. The one-shot flag bootstraps the tools it needs the first time it is used.

### base graph query

Ask the graph a question in plain language. It retrieves the relevant subgraph and synthesizes an answer.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph query "what did we decide about the docs domain"
base graph query "what did we decide about the docs domain" --depth 4 --token-budget 4000
base graph query "what did we decide about the docs domain" --raw
```

| Flag                            | Short | What it does                                           |
| ------------------------------- | ----- | ------------------------------------------------------ |
| `--depth <DEPTH>`               | `-d`  | How far to walk from the matched nodes. Defaults to 3. |
| `--token-budget <TOKEN_BUDGET>` | `-b`  | How much retrieved graph to keep. Defaults to 2000.    |
| `--model <MODEL>`               | `-m`  | Which model alias synthesizes the answer.              |
| `--raw`                         |       | Print the retrieved subgraph instead of an answer.     |

Use `--raw` when you want to check the retrieval rather than read the summary. If the right nodes are not in the raw output, the answer was never going to be right, and the fix is a wider `--depth` or a better question.

### base graph analyze

Show the emergent structure of the graph: the nodes everything connects to, the clusters, and the connections you would not have predicted.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph analyze
base graph analyze --top-n 25
```

| Flag              | Short | What it does                              |
| ----------------- | ----- | ----------------------------------------- |
| `--top-n <TOP_N>` | `-n`  | How many of each to show. Defaults to 10. |

### base graph get-node

Show one node in full: its label, type, source, summary and edges.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph get-node "basemode"
```

The argument can be a node label, a concept slug, or a substring unique enough to identify one node.

### base graph neighbors

Show a node's neighborhood as edge lines, expanded a given number of hops.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph neighbors "basemode"
base graph neighbors "basemode" --depth 2
```

| Flag              | Short | What it does                            |
| ----------------- | ----- | --------------------------------------- |
| `--depth <DEPTH>` | `-d`  | How many hops to expand. Defaults to 1. |

### base graph path

Show the shortest path between two nodes.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base graph path "basemode" "docs.basemode.ai"
```

Both arguments take a label, a slug, or a unique substring. This answers "how are these two things related at all", which is a different question from either node's neighborhood.

## Flat-file memories

Some memories live as files rather than in the graph. These two commands are for reviewing them and cleaning up the ones the graph already holds.

### base memory list

List the flat-file memories on this machine: name, type, description and path.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base memory list
```

### base memory purge

**Destructive.** Remove flat-file memories that have been confirmed as present in the graph.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base memory purge
```

Run `base memory list` first. This only removes files whose content the graph already has, but it removes them without asking.