<SYSTEM>This is the full developer documentation for Aictx</SYSTEM>

# Aictx documentation

> Public documentation for local-first project memory for AI coding agents.

Aictx gives AI coding agents a project memory they can come back to.

Use it when you are tired of re-explaining the same product intent, architecture decisions, repo conventions, setup steps, and known traps every time a new chat or agent session starts. Aictx stores that durable context as local, reviewable files under `.aictx/`, then compiles a focused context pack for the task in front of the agent.

The everyday loop is small:

```text
load relevant memory -> do the work -> save what future agents should remember
```

Core memory commands do not require a cloud account, embeddings, hosted sync, an external model API, or network access.

## What Aictx is for

[Section titled “What Aictx is for”](#what-aictx-is-for)

Aictx is local-first project memory for AI coding agents. It is not a chat UI, an Obsidian clone, or a hosted memory service.

It helps a coding agent answer two questions:

* Before work: what does this agent need to know for this task?
* After work: what should future agents not have to rediscover?

Memory can hold source records, decisions, constraints, facts, gotchas, workflows, open questions, product concepts, and compact syntheses for areas such as product intent, feature maps, roadmap, architecture, conventions, and agent guidance.

Tip

A good first memory is not a diary of what changed. It is something future agents can use: “release smoke tests run with `pnpm test:local`”, “billing webhooks retry in the worker”, or “the viewer is read-only except Obsidian export”.

## How it works

[Section titled “How it works”](#how-it-works)

1. Initialize Aictx inside an existing project with `aictx init`.
2. Load task-focused context with `aictx load "<task summary>"`.
3. Save durable knowledge with `aictx save --stdin` or `save_memory_patch` when MCP is already configured.
4. Inspect the result later with `aictx view`, `aictx diff`, Git tools, or MCP `diff_memory` when available.

Saved memory is active immediately after Aictx validates and writes it. Aictx never commits for you.

## Start here

[Section titled “Start here”](#start-here)

* [Getting started](/getting-started/) gets a project initialized and walks through the first load/save/diff loop.
* [Capabilities](/capabilities/) maps the v1 features to the jobs users and agents actually need to do.
* [Mental model](/mental-model/) explains canonical memory, generated state, object types, and retrieval.
* [Specializing Aictx](/specializing-aictx/) shows how to tailor memory to your repo’s product intent, workflows, and agent guidance.
* [Agent integration](/agent-integration/) gives agents the concrete workflow and guardrails.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

## For agents

[Section titled “For agents”](#for-agents)

This site is also published with agent-readable documentation files:

* `/llms.txt`
* `/llms-full.txt`
* `/llms-small.txt`

These files provide compact public documentation for coding agents without crawling the full website navigation.

# Agent integration

> How Aictx fits into a coding-agent workflow.

Aictx gives coding agents a local project-memory loop:

```text
load memory -> work -> save durable memory
```

The v1 agent model is CLI-first and MCP-compatible. Use the CLI by default. Use MCP only when the agent client has already launched and connected to `aictx-mcp`.

Aictx does not infer durable project meaning from diffs. The agent is responsible for semantic judgment: reading the task, loaded context, repository changes, tests, and conversation context, then deciding what future agents should remember.

## Routine workflow

[Section titled “Routine workflow”](#routine-workflow)

Before non-trivial coding, architecture, debugging, dependency, or configuration work:

```bash
aictx load "<task summary>"
aictx load "<task summary>" --mode debugging
aictx load "<task summary>" --file src/context/rank.ts --changed-file src/index/search.ts --history-window 30d
```

MCP equivalents are available only when the client already exposes Aictx MCP tools:

```text
load_memory({ task: "<task summary>", mode: "coding" })
load_memory({
  task: "<task summary>",
  mode: "coding",
  hints: {
    files: ["src/context/rank.ts"],
    changed_files: ["src/index/search.ts"],
    subsystems: ["retrieval"],
    history_window: "30d"
  }
})
```

Load modes are `coding`, `debugging`, `review`, `architecture`, and `onboarding`. Modes tune deterministic ranking and rendering only.

After meaningful work, save a structured patch only for durable knowledge that future agents should know:

```bash
aictx save --stdin
```

MCP equivalent when available:

```text
save_memory_patch({ patch: { source, changes } })
```

Saved memory is active immediately after Aictx validates and writes it. Dirty or untracked `.aictx/` files are not by themselves a reason to skip saving durable memory. When a save overwrites or deletes a dirty touched file, Aictx first backs it up under `.aictx/recovery/`.

Accepted memory can be inspected later:

```bash
aictx view
aictx diff
```

`aictx diff` includes tracked and untracked Aictx memory changes in Git projects. Aictx writes local files and never commits automatically.

When `aictx` is not on `PATH`, the same commands can run through the project package manager or local binary:

```bash
pnpm exec aictx load "<task summary>"
npm exec aictx load "<task summary>"
./node_modules/.bin/aictx load "<task summary>"
npx --package @aictx/memory -- aictx load "<task summary>"
pnpm exec aictx-mcp
npm exec aictx-mcp
./node_modules/.bin/aictx-mcp
npx --package @aictx/memory -- aictx-mcp
```

Tip

Save nothing when the task produced no durable future value. Aictx is meant to reduce repeated context work, not record every step an agent took.

## Capability reference

[Section titled “Capability reference”](#capability-reference)

The v1 agent model is CLI-first and MCP-compatible.

Local MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. CLI-only capabilities are v1 surfaces, not MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI remain future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search/inspect behavior, not local MCP tool names.

| Capability                     | MCP                 | CLI                         |
| ------------------------------ | ------------------- | --------------------------- |
| Load task context              | `load_memory`       | `aictx load`                |
| Search memory                  | `search_memory`     | `aictx search`              |
| Inspect object                 | `inspect_memory`    | `aictx inspect`             |
| Save memory patch              | `save_memory_patch` | `aictx save`                |
| Show memory diff               | `diff_memory`       | `aictx diff`                |
| Initialize storage             | none                | `aictx init`, `aictx setup` |
| Review patch file              | none                | `aictx patch review`        |
| Validate storage               | none                | `aictx check`               |
| Rebuild generated index        | none                | `aictx rebuild`             |
| Reset local storage            | none                | `aictx reset`               |
| Show memory history            | none                | `aictx history`             |
| Restore memory                 | none                | `aictx restore`             |
| Rewind memory                  | none                | `aictx rewind`              |
| List stale memory              | none                | `aictx stale`               |
| Show graph neighborhood        | none                | `aictx graph`               |
| Export Obsidian projection     | none                | `aictx export obsidian`     |
| Manage project registry        | none                | `aictx projects`            |
| View local memory              | none                | `aictx view`                |
| Suggest memory decision packet | none                | `aictx suggest`             |
| Audit memory hygiene           | none                | `aictx audit`               |
| Read public docs               | none                | `aictx docs`                |

For setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows, the CLI is the supported interface. Supported CLI or MCP save paths should handle `.aictx/` changes; editing `.aictx/` files directly is reserved for exceptional manual recovery or explicit user requests.

## Memory lifecycle

[Section titled “Memory lifecycle”](#memory-lifecycle)

Good memory stays narrow, durable, and current:

* Load narrowly before non-trivial work.
* Save only durable knowledge directly as active memory.
* Update existing memory before creating duplicates.
* Stale or supersede wrong old memory when current evidence invalidates it.
* Delete memory that should not persist.
* Prefer current code and user requests over loaded memory when they conflict.
* Report whether memory changed; async inspection is available through `aictx view`, `aictx diff`, or Git tools.
* Save nothing when the task produced no durable future value.

After failure or correction, treat the event as a memory-quality signal:

* Did the agent need missing project context?
* Did loaded memory conflict with current evidence?
* Did the user correct a stale assumption?
* Should existing memory be updated, marked stale, superseded, or deleted?
* Should an open `question`, `gotcha`, `source`, or `synthesis` be saved?

## Memory shape

[Section titled “Memory shape”](#memory-shape)

Right-size memory. Atomic memories should normally carry one durable claim. Use `synthesis` memories for compact area-level understanding that future agents should load quickly. Use `source` memories to preserve where context came from, especially repo docs, AGENTS/CLAUDE/rules, package manifests, issues, external references recorded by the agent, and user-stated context.

Use relations only when the link matters. Common predicates include `derived_from`, `summarizes`, `documents`, `requires`, `depends_on`, `affects`, and `supersedes`.

Update-before-create behavior keeps memory from drifting into duplicates:

* `update_object` refreshes an existing object.
* `mark_stale` records that old memory is wrong or no longer useful.
* `supersede_object` connects old memory to its replacement.
* `delete_object` removes memory that should not persist.
* `create_relation` records a durable, useful link between objects.

Create a new object only when no existing memory should be updated, marked stale, or superseded.

Save-nothing-is-valid policy: if the work produced no durable future value, do not invent a patch. Tell the user that no Aictx memory was saved.

## Object taxonomy

[Section titled “Object taxonomy”](#object-taxonomy)

Object types are `project`, `architecture`, `decision`, `constraint`, `question`, `fact`, `gotcha`, `workflow`, `note`, `concept`, `source`, and `synthesis`.

`history`, `task-note`, and `feature` are not object types. Git, events, and statuses cover history. Branch or task scope covers temporary task context. Product capabilities fit `concept` objects or `synthesis` objects with feature facets.

`gotcha` fits known failure modes and traps. `workflow` fits repeated project procedures. Organization facets such as `domain`, `bounded-context`, `capability`, `business-rule`, and `unresolved-conflict` are optional plain-language retrieval hints, not mandatory DDD terminology.

Durable syntheses should usually have source evidence or active source provenance relations.

## Examples

[Section titled “Examples”](#examples)

Good memory examples:

* Good durable fact: a `fact` titled “Webhook retries run in the worker” with one sentence naming the current retry location.
* Good linked decision: `decision.billing-retries` plus a `requires` relation to `constraint.webhook-idempotency` when the decision depends on that constraint.
* Good gotcha: `gotcha.viewer-export-overwrites-manifest-files` when a repeated failure mode affects future work.
* Good workflow: `workflow.release-smoke-test` for a repeated project procedure.
* Good source-backed synthesis: `synthesis.product-intent` summarizes what the product is for and has `derived_from` relations to source records.

Bad memory examples:

* Duplicate creation: creating a second memory for the same durable claim instead of updating, marking stale, or superseding the existing one.
* Task diary: saving “I changed three files and ran tests” when Git history already records the work.
* Speculation: saving guesses that are not supported by current evidence.
* No-value save: creating a memory patch only to say that nothing important happened.

Secrets, tokens, credentials, private keys, sensitive raw logs, unsupported speculation, and unrelated user preferences should not be saved as memory. Memory should never ask future agents to ignore current code, tests, user requests, or safety rules.

## Bootstrap and suggestion packets

[Section titled “Bootstrap and suggestion packets”](#bootstrap-and-suggestion-packets)

`aictx setup` provides guided first-run onboarding. When loaded memory only contains starter placeholders, setup and onboarding requests are enough context for the bootstrap workflow.

```bash
aictx suggest --bootstrap --json
aictx suggest --bootstrap --patch > bootstrap-memory.json
aictx patch review bootstrap-memory.json
aictx save --file bootstrap-memory.json
aictx check
```

`aictx suggest --from-diff --json` creates a memory suggestion packet from current code changes. `aictx audit --json` reports grouped, actionable memory hygiene issues.

During setup, product features can use the `product-feature` facet. Source-backed syntheses are a good fit for product intent, feature maps, roadmap, architecture, conventions, agent guidance, and repeated workflows.

For the full memory-quality loop, see [Demand-driven memory](/demand-driven-memory/).

# Capabilities

> What Aictx can do in v1, grouped by user and agent jobs.

Aictx is intentionally narrow: it gives coding agents a local memory substrate, then leaves semantic judgment to the agent and review to the developer.

This page maps the v1 feature set to the jobs you will actually do.

## Routine memory work

[Section titled “Routine memory work”](#routine-memory-work)

Use these on most tasks:

```bash
aictx load "fix Stripe webhook retries"
aictx search "webhook retry convention"
aictx inspect decision.billing-retries
aictx save --stdin
aictx diff
```

* `load` compiles task-focused context.
* `search` finds memory without loading a full context pack.
* `inspect` opens one memory object and its direct relations.
* `save` writes a structured patch after validation.
* `diff` shows tracked and untracked `.aictx/` changes in Git projects.

Tip

Start with `load`, not `search`, for normal coding tasks. `load` gives the agent a compact working packet; `search` is better when you already know the kind of memory you are looking for.

## Setup and bootstrap

[Section titled “Setup and bootstrap”](#setup-and-bootstrap)

Use these when a project is new to Aictx or memory feels too thin:

```bash
aictx init
aictx setup
aictx setup --apply
aictx suggest --bootstrap --patch > bootstrap-memory.json
aictx patch review bootstrap-memory.json
```

`init` creates local storage and optional repo-level agent guidance. `setup` orchestrates the first-run bootstrap path so Aictx can seed source-backed project intent, feature map, roadmap, architecture, conventions, and agent guidance when current repo evidence supports it.

## Memory quality and maintenance

[Section titled “Memory quality and maintenance”](#memory-quality-and-maintenance)

Use these when memory needs cleanup, review, or a save/no-save decision:

```bash
aictx suggest --after-task "fix Stripe webhook retries" --json
aictx suggest --from-diff --json
aictx audit --json
aictx stale
aictx graph <id>
```

* `suggest --after-task` gives an agent a read-only decision packet at the end of work.
* `suggest --from-diff` looks at current Git changes and proposes memory maintenance ideas.
* `audit` reports deterministic hygiene issues.
* `stale` lists stale and superseded memory.
* `graph` shows a one-hop relation neighborhood for debugging.

Tip

When a user correction reveals that old memory was wrong, prefer updating, marking stale, superseding, or deleting the existing object over creating another near-duplicate.

## Human inspection

[Section titled “Human inspection”](#human-inspection)

Use these when you want to inspect memory without editing raw `.aictx/` files:

```bash
aictx view --open
aictx projects list
aictx export obsidian
aictx docs
```

`aictx view` starts a local, read-only browser viewer. `projects` manages the user-level registry used by the viewer. `export obsidian` writes a generated Obsidian-compatible projection. `docs` prints bundled public docs or opens the hosted docs site.

## Validation and recovery

[Section titled “Validation and recovery”](#validation-and-recovery)

Use these when storage, indexes, or Git-backed history need attention:

```bash
aictx check
aictx rebuild
aictx upgrade
aictx history
aictx restore <commit>
aictx rewind
aictx reset
```

* `check` validates canonical memory and generated index health.
* `rebuild` recreates generated indexes from canonical memory.
* `upgrade` migrates supported storage to the latest schema.
* `history`, `restore`, and `rewind` use Git when available.
* `reset` backs up and clears local Aictx storage.

## MCP equivalents

[Section titled “MCP equivalents”](#mcp-equivalents)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

# CLI guide

> Setup, routine work, inspection, recovery, export, docs, and viewer commands.

The CLI is the default interface for Aictx. It is the quickest path for setup, routine memory work, inspection, recovery, export, documentation, and the local viewer.

Most days, an agent only needs:

```bash
aictx load "task summary"
aictx save --stdin
aictx diff
```

The rest of the CLI is there for setup, review, recovery, and maintenance.

## Quick checks

[Section titled “Quick checks”](#quick-checks)

```bash
aictx check
aictx diff
aictx view --open
```

* `check` validates canonical memory and generated index health.
* `diff` shows memory changes, including untracked files in Git projects.
* `view --open` starts the local read-only browser viewer.

## Setup and bootstrap

[Section titled “Setup and bootstrap”](#setup-and-bootstrap)

```bash
aictx init
aictx setup
aictx setup --apply
aictx patch review bootstrap-memory.json
```

* `init` creates `.aictx/` and optional repo-level agent guidance.
* `setup` guides first-run onboarding and bootstrap memory preview.
* `setup --apply` applies the conservative bootstrap memory patch immediately.
* `patch review` reviews a structured memory patch without writing it.

Tip

If memory is empty after `init`, use `aictx setup` before hand-writing memory. The bootstrap flow is designed for exactly that first-run gap.

## Routine memory work

[Section titled “Routine memory work”](#routine-memory-work)

```bash
aictx load "change auth routes"
aictx search "auth route conventions"
aictx inspect decision.auth-route-conventions
aictx suggest --after-task "change auth routes" --json
aictx audit --json
aictx save --stdin
```

The routine loop is narrow load, work, and save only durable knowledge as active memory. A task that produced no reusable project knowledge does not need a save.

Commands that support structured output accept `--json`:

```bash
aictx check --json
```

## Inspection and debugging

[Section titled “Inspection and debugging”](#inspection-and-debugging)

```bash
aictx stale
aictx graph <id>
```

`stale` lists stale and superseded memory. `graph` shows a one-hop relation neighborhood for debugging retrieval and provenance.

## Maintenance

[Section titled “Maintenance”](#maintenance)

```bash
aictx check
aictx rebuild
aictx upgrade
aictx reset
aictx reset --all
```

`rebuild` regenerates indexes from canonical memory. `reset` backs up and clears local `.aictx/` storage. `reset --all` resets every project in the user-level registry; add `--destroy` only when you intend to delete each registered `.aictx/` without backup.

## Git inspection and recovery

[Section titled “Git inspection and recovery”](#git-inspection-and-recovery)

```bash
aictx diff
aictx history
aictx restore <commit>
aictx rewind
```

Aictx writes local files and never commits automatically. Git remains the source of truth for history and rollback when the project is inside a Git worktree.

## Export, viewer, and docs

[Section titled “Export, viewer, and docs”](#export-viewer-and-docs)

```bash
aictx export obsidian
aictx projects list
aictx view --open
aictx docs
aictx docs getting-started
aictx docs demand-driven-memory
aictx docs agent-integration --open
```

`aictx view` starts a local, read-only memory viewer. `aictx docs` lists bundled public docs topics. `aictx docs <topic>` prints bundled Markdown for that topic. `--open` opens the hosted docs site.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

# Demand-driven memory

> How real agent failure, confusion, and correction improve durable project memory.

Aictx is most useful when memory quality improves from real work.

When an agent fails, asks for missing project context, finds stale assumptions, or receives a correction from the user, that event is evidence. It may mean the project memory needs to be updated, marked stale, superseded, deleted, or expanded with a better source-backed summary.

The loop is:

```text
load -> work/fail/correction -> identify memory gap -> save memory repair
```

## What counts as a signal

[Section titled “What counts as a signal”](#what-counts-as-a-signal)

A task is a memory-quality signal when it reveals durable context that future agents should not rediscover:

* Missing architecture, workflow, or product context blocked the task.
* Loaded memory contradicted current code, tests, docs, or the user request.
* The user corrected an assumption that is likely to recur.
* Two active memories conflict and the agent cannot safely choose between them.
* Knowledge was tribal: only the user knew it, but future agents will need it.

Tip

The best memory repairs often come from friction. If an agent made a plausible wrong assumption, capture the corrected fact or mark the stale memory so the next agent does not repeat it.

## Repair with existing primitives

[Section titled “Repair with existing primitives”](#repair-with-existing-primitives)

Existing Aictx objects cover the common repair cases:

* `source` for provenance.
* `question` for missing knowledge or unresolved conflict.
* `gotcha` for repeated failure modes.
* `synthesis` for compact maintained context.
* `decision`, `constraint`, `fact`, `workflow`, and `concept` for precise claims.
* Relations when the link matters.

Facets such as `domain`, `bounded-context`, `capability`, `business-rule`, and `unresolved-conflict` are organization hints. They are optional and should stay plain-language.

## When to save nothing

[Section titled “When to save nothing”](#when-to-save-nothing)

Save nothing when the task produced no durable future value. Passing tests, renaming a local variable, or trying a temporary debugging command usually does not need memory.

Save memory when future agents would otherwise waste time, repeat a mistake, or need user correction to learn the same thing.

# Getting started

> Install Aictx, initialize memory, and run the first load/save loop.

Aictx works inside an existing project. By the end of this page you will have a local `.aictx/` directory, repo-level agent guidance, and the commands for the first memory loop.

## What you need

[Section titled “What you need”](#what-you-need)

* Node.js `>=22`
* A project directory where you want AI coding agents to remember durable project context

Check Node with:

```bash
node --version
```

## Install

[Section titled “Install”](#install)

Install globally for the simplest CLI and MCP setup:

```bash
npm install -g @aictx/memory
```

Global install is the recommended default for regular CLI use and optional MCP use. A project-local dependency is only needed when a project should pin its own Aictx version.

For project-local version pinning:

```bash
pnpm add -D @aictx/memory
npm install -D @aictx/memory
```

When `aictx` is not on `PATH`, run commands through the package manager or local binary:

```bash
pnpm exec aictx init
npm exec aictx init
./node_modules/.bin/aictx init
```

For one-off execution without a global or local install:

```bash
pnpm --package @aictx/memory dlx aictx init
npx --package @aictx/memory -- aictx init
```

## Initialize a project

[Section titled “Initialize a project”](#initialize-a-project)

From the project root:

```bash
aictx init
```

`init` creates `.aictx/` and, by default, updates marked Aictx sections in `AGENTS.md` and `CLAUDE.md`. Those sections tell coding agents to load memory before non-trivial work and make a save/no-save decision after meaningful work.

Use `--no-agent-guidance` when you want to leave those instruction files unchanged.

Tip

`aictx init` creates starter storage. It does not try to understand your whole project from scratch. Use the setup flow next when you want Aictx to seed useful first-run memory from existing repo evidence.

## Seed first-run memory

[Section titled “Seed first-run memory”](#seed-first-run-memory)

For guided onboarding:

```bash
aictx setup
aictx setup --apply
```

`aictx setup` previews a conservative bootstrap memory patch. `aictx setup --apply` applies it immediately.

If you want to inspect the patch file manually:

```bash
aictx suggest --bootstrap --patch > bootstrap-memory.json
aictx patch review bootstrap-memory.json
aictx save --file bootstrap-memory.json
aictx check
```

This is the right path when memory feels empty after `init`, or when you want source-backed product intent, feature map, roadmap, architecture, conventions, and agent guidance syntheses without hand-writing JSON.

## Run the first memory loop

[Section titled “Run the first memory loop”](#run-the-first-memory-loop)

Load memory before non-trivial work:

```bash
aictx load "change auth routes"
```

After work creates durable knowledge for future agents, save a structured patch:

```bash
aictx save --stdin
```

Saved memory is active immediately after Aictx validates and writes it. A task that produced no reusable project knowledge does not need a save.

Inspect memory later:

```bash
aictx view
aictx diff
```

Tip

Use `aictx diff` for memory review in Git projects. Plain `git diff -- .aictx/` can miss untracked memory files before they are staged.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

# MCP guide

> Configure Aictx MCP and understand the CLI/MCP capability boundary.

`aictx-mcp` is an MCP stdio server. Configure your MCP client to launch the global binary, or a project-local binary when the project pins Aictx.

MCP is useful when the agent client already supports MCP tools. The CLI remains the default path for routine memory work and all setup, maintenance, recovery, viewer, docs, suggestion, audit, stale, and graph workflows.

Tip

`aictx init` does not start MCP. Starting `aictx-mcp` in a shell usually cannot add MCP tools to an already-running agent session. Configure the client first, then start a new session.

## Install

[Section titled “Install”](#install)

A global install gives the simplest setup:

```bash
npm install -g @aictx/memory
```

The MCP client can launch the global binary:

```bash
aictx-mcp
```

With a project-local package install, the client can launch through the project package manager:

```bash
pnpm exec aictx-mcp
npm exec aictx-mcp
```

For one-off package resolution, name the scoped package explicitly:

```bash
npx --package @aictx/memory -- aictx-mcp
```

For a local binary path, configure the client to launch:

```bash
./node_modules/.bin/aictx-mcp
```

MCP uses stdout for the protocol. Startup diagnostics and failures are written to stderr.

## Tools

[Section titled “Tools”](#tools)

Local MCP exposes exactly these tools in v1:

* `load_memory`
* `search_memory`
* `inspect_memory`
* `save_memory_patch`
* `diff_memory`

MCP equivalents are available when the client already exposes Aictx MCP tools:

```text
load_memory({ task: "<task summary>", mode: "coding" })
search_memory({ query: "auth route conventions" })
inspect_memory({ id: "decision.auth-route-conventions" })
save_memory_patch({ patch: { source, changes } })
diff_memory({})
```

When the MCP server was launched globally rather than from the project root, `project_root` selects the initialized project:

```text
load_memory({
  project_root: "/path/to/project",
  task: "<task summary>",
  mode: "coding"
})
```

`project_root` selects an initialized local Aictx project for the tool call. It is not arbitrary filesystem access; reads and writes remain scoped to the resolved project’s `.aictx/` directory.

## CLI-only boundaries

[Section titled “CLI-only boundaries”](#cli-only-boundaries)

Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1:

* Setup: `aictx init`, `aictx setup`
* Maintenance: `aictx check`, `aictx rebuild`, `aictx reset`, `aictx upgrade`
* Recovery: `aictx history`, `aictx restore`, `aictx rewind`
* Export: `aictx export obsidian`
* Registry: `aictx projects`
* Viewer: `aictx view`
* Docs: `aictx docs`
* Suggest and audit: `aictx suggest`, `aictx audit`
* Stale and graph inspection: `aictx stale`, `aictx graph`

These CLI-only commands are part of the v1 integration model rather than MCP parity gaps. Local viewing remains a browser inspection surface, not a routine MCP memory operation, so `aictx view` has no MCP equivalent.

Future ChatGPT-compatible or other host adapters may expose generic `search` and `fetch` names as aliases over Aictx search and inspect behavior. Those names are future adapter mappings only. The local MCP server exposes the five Aictx-specific tools above; generic `search` and `fetch` are not local MCP tool names.

Local MCP is the near-term integration path for MCP-capable local agent harnesses. Remote MCP endpoints, hosted sync, cloud APIs, OAuth or cloud-auth surfaces, tenancy layers, billing surfaces, and ChatGPT App SDK UI remain future work.

# Mental model

> How Aictx stores, indexes, retrieves, and inspects project memory.

Aictx is a memory discipline system, not just a folder of notes.

The goal is simple: future agents should not restart from zero. They should load the durable context that matters, do the task, and save only the reusable knowledge future agents can safely rely on.

## The short version

[Section titled “The short version”](#the-short-version)

```text
canonical memory -> generated index -> task-focused context pack
```

Canonical memory is the durable source of truth. Generated state is rebuildable. The context pack is what an agent gets for a specific task.

## Canonical memory

[Section titled “Canonical memory”](#canonical-memory)

`.aictx/` contains canonical memory and generated support files.

Canonical memory includes human-readable Markdown bodies, JSON sidecars with structured metadata, relation JSON files, and `events.jsonl` for semantic memory history. Saved memory is accepted as active memory immediately after Aictx validates and writes it.

Generated state is rebuildable. The SQLite search index, context packs, and exports can be regenerated from canonical memory. Supported Aictx commands are the normal way to recreate generated state:

```bash
aictx check
aictx rebuild
```

## Hybrid memory model

[Section titled “Hybrid memory model”](#hybrid-memory-model)

Aictx uses three layers:

* `source` records preserve where context came from, such as README files, package manifests, AGENTS/CLAUDE/rules, issues, external references recorded by an agent, or user-stated context.
* Atomic memories capture precise reusable claims as `decision`, `constraint`, `fact`, `gotcha`, `workflow`, `question`, `note`, or `concept` objects.
* `synthesis` records maintain compact summaries for product intent, feature maps, roadmap, architecture, conventions, agent guidance, and repeated workflows.

Object types are `project`, `architecture`, `source`, `synthesis`, `decision`, `constraint`, `question`, `fact`, `gotcha`, `workflow`, `note`, and `concept`. `history`, `task-note`, and `feature` are not object types. Git, events, and object statuses cover history. Branch or task scope covers temporary task context. Product capabilities fit `concept` objects or `synthesis` objects with feature facets.

Tip

Keep memories shaped like things future agents can use. A `synthesis` should replace rereading scattered docs. An atomic memory should normally carry one durable claim.

## Demand-driven memory quality

[Section titled “Demand-driven memory quality”](#demand-driven-memory-quality)

Real work improves memory quality. Agent failure, confusion, stale loaded context, and user correction are signals that durable memory may need repair.

The lean loop is:

```text
load -> work/fail/correction -> identify memory gap -> save memory repair
```

See [Demand-driven memory](/demand-driven-memory/) for the user-facing workflow.

## Retrieval

[Section titled “Retrieval”](#retrieval)

`aictx load "<task summary>"` compiles a task-focused context pack. Load modes such as `coding`, `debugging`, `review`, `architecture`, and `onboarding` tune deterministic ranking and rendering. They do not broaden the project scope, call a model, use external retrieval, or load the whole project.

Use `aictx search "<query>"` when you need targeted lookup. Use `aictx inspect <id>` when you already know which memory object matters.

## Async inspection

[Section titled “Async inspection”](#async-inspection)

Aictx writes inspectable files. The local viewer and, in Git projects, the memory diff show the current state:

```bash
aictx view
aictx diff
```

Plain `git diff -- .aictx/` can omit untracked memory files before staging. `aictx diff` includes tracked and untracked Aictx memory changes.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

# Reference

> Compact CLI, MCP, docs, object taxonomy, and structured patch reference.

Use this page when you need exact names, commands, and patch shapes.

## CLI commands

[Section titled “CLI commands”](#cli-commands)

The CLI is the default interface for routine memory work.

| Area                    | Commands                                                                   |
| ----------------------- | -------------------------------------------------------------------------- |
| Setup                   | `aictx init`, `aictx setup`                                                |
| Maintenance             | `aictx check`, `aictx rebuild`, `aictx reset`, `aictx upgrade`             |
| Routine memory          | `aictx load`, `aictx search`, `aictx suggest`, `aictx audit`, `aictx save` |
| Inspection              | `aictx inspect`, `aictx stale`, `aictx graph`                              |
| Inspection and recovery | `aictx diff`, `aictx history`, `aictx restore`, `aictx rewind`             |
| Export                  | `aictx export obsidian`                                                    |
| Viewer                  | `aictx projects`, `aictx view`                                             |
| Docs                    | `aictx docs`                                                               |

Commands that support structured output accept `--json`:

```bash
aictx check --json
aictx docs --json
```

## MCP tools

[Section titled “MCP tools”](#mcp-tools)

MCP is available when the agent client already exposes Aictx MCP tools. Local MCP exposes exactly:

* `load_memory`
* `search_memory`
* `inspect_memory`
* `save_memory_patch`
* `diff_memory`

Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search/inspect behavior; they are not local MCP tool names.

## Docs command

[Section titled “Docs command”](#docs-command)

```bash
aictx docs
aictx docs getting-started
aictx docs capabilities
aictx docs specializing-aictx
aictx docs agent-integration --open
aictx docs --json
```

`aictx docs` lists bundled public docs topics. `aictx docs <topic>` prints the bundled Markdown for that topic. `--open` opens the hosted page at `https://docs.aictx.dev`.

## Object types

[Section titled “Object types”](#object-types)

Object types are `project`, `architecture`, `source`, `synthesis`, `decision`, `constraint`, `question`, `fact`, `gotcha`, `workflow`, `note`, and `concept`.

`history`, `task-note`, and `feature` are not object types.

Facet categories include `project-description`, `architecture`, `stack`, `convention`, `file-layout`, `product-feature`, `testing`, `decision-rationale`, `abandoned-attempt`, `workflow`, `gotcha`, `debugging-fact`, `source`, `product-intent`, `feature-map`, `roadmap`, `agent-guidance`, `concept`, `open-question`, `domain`, `bounded-context`, `capability`, `business-rule`, and `unresolved-conflict`.

## Structured patch

[Section titled “Structured patch”](#structured-patch)

The structured patch is the only write contract.

```json
{
  "source": {
    "kind": "agent",
    "task": "Fix Stripe webhook retries"
  },
  "changes": [
    {
      "op": "create_object",
      "type": "decision",
      "title": "Billing retries moved to queue worker",
      "body": "Stripe webhook retries now happen in the queue worker.",
      "tags": ["billing", "stripe"]
    }
  ]
}
```

Patch operations include `create_object`, `update_object`, `mark_stale`, `supersede_object`, `delete_object`, `create_relation`, `update_relation`, and `delete_relation`.

Structured patches are for durable information future agents should know. A task that produced no durable future value does not need a save.

# Specializing Aictx

> Tailor Aictx memory to a project, team, repo, and agent workflow.

Aictx works out of the box, but it becomes much more useful when memory matches the shape of your project.

Specializing Aictx does not mean designing a big ontology. It means teaching future agents the context a teammate would normally pick up over time: what the product is for, which workflows matter, where traps live, what conventions are current, and which facts are source-backed.

## Start with repo guidance

[Section titled “Start with repo guidance”](#start-with-repo-guidance)

By default, `aictx init` updates marked Aictx sections in `AGENTS.md` and `CLAUDE.md`. Keep those sections short and reviewable. They should tell agents when to load memory, when to save durable memory, and when saving nothing is the right answer.

If your agent client uses optional skills or instruction files, Aictx also ships copyable generated guidance under `integrations/`. These files are setup aids, not canonical memory.

Tip

Treat agent guidance as the operating manual, and `.aictx/` memory as the project knowledge the agent can retrieve. Keep both small enough that a human can audit them.

## Seed the project shape

[Section titled “Seed the project shape”](#seed-the-project-shape)

For a new project, run:

```bash
aictx setup
```

or apply the conservative bootstrap directly:

```bash
aictx setup --apply
```

For manual review:

```bash
aictx suggest --bootstrap --patch > bootstrap-memory.json
aictx patch review bootstrap-memory.json
aictx save --file bootstrap-memory.json
aictx check
```

Good bootstrap memory usually includes:

* `source` records for README files, package manifests, agent guidance, product docs, or stable external references recorded by an agent.
* `synthesis` records for product intent, feature map, roadmap, architecture, conventions, agent guidance, and repeated workflows.
* Atomic `decision`, `constraint`, `fact`, `gotcha`, `workflow`, `question`, `note`, or `concept` objects only when a precise durable claim is useful.

Do not invent product features from weak signals. Source-backed memory is much easier to trust and repair later.

## Decide what belongs in memory

[Section titled “Decide what belongs in memory”](#decide-what-belongs-in-memory)

Save durable project knowledge, not task diaries.

Good candidates:

* product intent that explains why the app exists
* capabilities and feature boundaries
* architecture decisions and constraints
* setup, release, migration, or debugging workflows
* gotchas and repeated failure modes
* current conventions that affect future edits
* open questions that block safe implementation
* source records for user-stated durable context

Bad candidates:

* “I edited three files and tests passed”
* guesses that are not supported by code, docs, or the user
* secrets, tokens, credentials, private keys, or sensitive raw logs
* temporary implementation notes with no future value

Tip

If a memory would be obsolete as soon as the current branch is merged, it is probably task context, not durable project memory.

## Maintain it after real work

[Section titled “Maintain it after real work”](#maintain-it-after-real-work)

At the end of meaningful work, ask for a read-only save/no-save packet when useful:

```bash
aictx suggest --after-task "change auth routes" --json
```

When current code changes are already present:

```bash
aictx suggest --from-diff --json
```

When memory feels noisy or contradictory:

```bash
aictx audit --json
aictx stale
aictx graph <id>
```

Failure and correction are useful signals. If loaded memory contradicted current code, tests, docs, or the user request, repair the old memory. Update it, mark it stale, supersede it, or delete it instead of piling on a duplicate.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.

# Troubleshooting

> Fix common install, PATH, MCP, schema, index, and recovery issues.

Start with the smallest check that answers the question:

```bash
aictx check
aictx diff
aictx view --open
```

`check` validates storage and index health. `diff` shows memory changes. `view` opens the local read-only inspection UI.

## `aictx` is not on PATH

[Section titled “aictx is not on PATH”](#aictx-is-not-on-path)

Package-manager and local-binary forms work without a global `PATH` entry:

```bash
pnpm exec aictx check
npm exec aictx check
./node_modules/.bin/aictx check
```

For one-off execution:

```bash
npx --package @aictx/memory -- aictx check
```

If a project-local install is stale, update it or use a current global/source binary before trusting schema errors.

## MCP tools are not available

[Section titled “MCP tools are not available”](#mcp-tools-are-not-available)

`aictx init` creates local storage. It does not start MCP. MCP tools become available when the MCP client is configured to launch `aictx-mcp`.

An agent generally cannot start `aictx-mcp` in a shell and then use it as MCP tools in an already-running session. When MCP tools are not available, the CLI path provides the same routine memory workflow.

Local MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory` when the client already exposes Aictx tools. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows remain CLI-only.

Local MCP is the near-term integration path. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK surfaces are future work, and future `search`/`fetch` adapter names are not local MCP tool names.

Tip

If you need to keep working right now, use `aictx load` and `aictx save --stdin` from the CLI. Configure MCP later in the client settings.

## Memory is empty after init

[Section titled “Memory is empty after init”](#memory-is-empty-after-init)

`aictx init` creates starter storage. It does not infer a full project memory model by itself.

Guided setup:

```bash
aictx setup
```

or ask for a bootstrap patch:

```bash
aictx suggest --bootstrap --patch > bootstrap-memory.json
aictx patch review bootstrap-memory.json
aictx save --file bootstrap-memory.json
aictx check
```

The bootstrap path is best for first-run product intent, feature map, roadmap, architecture, conventions, and agent guidance memory.

## Schema or index errors

[Section titled “Schema or index errors”](#schema-or-index-errors)

Storage validation:

```bash
aictx check
```

Generated index rebuild:

```bash
aictx rebuild
```

`rebuild` does not change canonical memory.

## Dirty memory warnings

[Section titled “Dirty memory warnings”](#dirty-memory-warnings)

Dirty or untracked `.aictx/` files are not by themselves a reason to skip saving durable memory. Review the files, then use supported CLI/MCP save paths when there is durable future value. Aictx backs up dirty touched files under `.aictx/recovery/` before overwrite/delete and continues where possible.

## Git diff misses new memory files

[Section titled “Git diff misses new memory files”](#git-diff-misses-new-memory-files)

The Aictx diff includes tracked and untracked memory files:

```bash
aictx diff
```

Plain `git diff -- .aictx/` can omit untracked memory files before staging.

# Local viewer

> Read-only local browser viewer for project memory inspection.

`aictx view` starts a local, read-only browser viewer for human inspection.

```bash
aictx view
aictx view --open
aictx view --port 4888
aictx view [--port <number>] [--open] [--detach] [--json]
```

Use it when you want to browse memory objects, source-backed syntheses, relations, project registry entries, and generated Obsidian export state without editing canonical `.aictx/` files.

The command binds only to `127.0.0.1`, chooses an available random port by default, and prints a local URL that includes a per-run API token. It can start outside an initialized project and opens to a Projects dashboard populated from the user-level registry, plus the current project when the launch directory is initialized.

## Projects

[Section titled “Projects”](#projects)

The registry lives at `$AICTX_HOME/projects.json`, defaulting to `~/.aictx/projects.json`. It stores only project metadata and roots. Canonical memory stays isolated in each project’s own `.aictx/` directory.

Project registry commands:

```bash
aictx projects list
aictx projects add
aictx projects add /path/to/project
aictx projects remove <registry-id|project-id|path>
aictx projects prune
```

Tip

The project registry is for discovery in the viewer. It is not shared memory and does not make project IDs globally unique.

## Read-only boundary

[Section titled “Read-only boundary”](#read-only-boundary)

The viewer does not edit canonical memory. It is not a hosted app, remote API, MCP tool, Obsidian plugin, or knowledge-management system.

The only write action in the viewer is the explicit Obsidian export screen, which calls the same generated projection service as:

```bash
aictx export obsidian
```

That export writes generated projection files only.

`aictx view` is CLI-only in v1 and has no MCP equivalent.

## CLI and MCP

[Section titled “CLI and MCP”](#cli-and-mcp)

The CLI is the default interface for routine memory work. MCP is available when the agent client has launched and connected to `aictx-mcp`.

MCP exposes exactly `load_memory`, `search_memory`, `inspect_memory`, `save_memory_patch`, and `diff_memory`. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible `search`/`fetch` names are adapter aliases over search and inspect behavior, not local MCP tool names.