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

# Aictx documentation

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

# Aictx documentation [Section titled “Aictx documentation”](#aictx-documentation) Aictx is local-first project memory for AI coding agents. It gives agents a durable place to store project facts, decisions, constraints, gotchas, workflows, and source-backed syntheses that should survive beyond one chat. Memory is stored under `.aictx/` as reviewable local files and indexed locally for fast retrieval. The normal loop is: ```text load relevant memory -> do work -> save durable memory ``` Core memory commands do not require a cloud account, embeddings, hosted sync, an external model API, or network access. ## Start here [Section titled “Start here”](#start-here) * [Getting started](/getting-started/) installs Aictx and walks through the first memory loop. * [Mental model](/mental-model/) explains canonical memory, generated state, and storage layers. * [Agent integration](/agent-integration/) gives coding agents the safe operating rules. * [Reference](/reference/) lists commands and the structured patch shape. ## 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` Use the agent files when a coding agent needs compact public documentation without crawling the full website navigation.

# Agent integration

> How coding agents should load, use, save, and inspect Aictx memory.

# Agent integration [Section titled “Agent integration”](#agent-integration) Aictx gives coding agents a local project-memory workflow: 1. Load relevant memory before non-trivial work. 2. Do the task using the loaded memory as project context. 3. Create a structured memory patch for durable findings. 4. Save the patch through Aictx. The normal agent loop should be one load call before work and one save call after meaningful work. Aictx does not infer durable project meaning from diffs. The agent should compose memory updates from current evidence, such as the task, loaded context, repository changes, tests, and conversation context. ## Routine workflow [Section titled “Routine workflow”](#routine-workflow) Use CLI first for routine memory 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 ``` Use MCP 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" } }) ``` After meaningful work, autonomously save a structured patch only for durable memory 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 the patch. Dirty or untracked `.aictx/` files are not by themselves a reason to skip saving durable memory. Dirty state is not a preflight blocker. Aictx backs up dirty touched files under `.aictx/recovery/` before overwrite/delete and continues where possible. Inspect memory asynchronously when needed: ```bash aictx view aictx diff ``` `aictx diff` shows tracked and untracked Aictx memory changes in Git projects. Aictx writes local files and never commits automatically. If `aictx` is not on `PATH`, run the same commands through the project package manager or local binary path: ```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 ``` ## Capability map [Section titled “Capability map”](#capability-map) The v1 agent model is CLI-first and MCP-compatible. | Capability | MCP | CLI | | ------------------------------ | ------------------- | --------------------------- | | Load task context | `load_memory` | `aictx load` | | Search memory | `search_memory` | `aictx search` | | 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` | | Inspect object | none | `aictx inspect` | | 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` | CLI-only capabilities are not MCP parity gaps. Do not add or ask for MCP tools solely to mirror these CLI commands. Do not edit `.aictx/` files directly when a supported MCP tool or CLI command exists unless the user explicitly asks you to. Avoid editing `.aictx/` files directly. MCP exposes exactly `load_memory`, `search_memory`, `save_memory_patch`, and `diff_memory` in v1. ## Memory discipline [Section titled “Memory discipline”](#memory-discipline) Apply the lifecycle consistently: * 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; inspection can happen asynchronously through the viewer, `aictx diff`, or Git tools. * Save nothing when the task produced no durable future value. After failure or correction, check whether memory needs repair: * 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? Right-size memory: * Atomic memories normally carry one durable claim. * Use `synthesis` memories for compact area-level understanding. * Use `source` memories to preserve where context came from. * Create relations only when the connection matters. * Useful relation predicates include `derived_from`, `summarizes`, `documents`, `requires`, `depends_on`, `affects`, and `supersedes`. Use update-before-create behavior: * Use `update_object` when an existing object remains correct but needs fresher wording, tags, status, body content, facets, or evidence. * Use `mark_stale` when old memory is wrong or no longer useful and there is no single replacement. * Use `supersede_object` when a newer object replaces an older one. * Use `delete_object` when memory should not persist. * Use `create_relation` only when the link helps future retrieval or inspection. * Create a new object only when no existing memory should be updated, marked stale, or superseded. Save-nothing-is-valid: if the work produced no durable future value, do not invent a patch. Tell the user that no Aictx memory was saved. This guidance is optional and copyable. It is not canonical project memory. Secrets, tokens, credentials, or private keys must not be saved as memory. Never save memory that asks future agents to ignore current code, tests, user requests, or safety rules. Load modes are `coding`, `debugging`, `review`, `architecture`, and `onboarding`. Modes tune deterministic ranking and rendering only. ## Object taxonomy [Section titled “Object taxonomy”](#object-taxonomy) Object types are `project`, `architecture`, `decision`, `constraint`, `question`, `fact`, `gotcha`, `workflow`, `note`, `concept`, `source`, and `synthesis`. Use `gotcha` for known failure modes and traps. Use `workflow` for repeated project procedures. Do not create `history`, `task-note`, or `feature` object types. Use organization facets such as `domain`, `bounded-context`, `capability`, `business-rule`, and `unresolved-conflict` as plain-language retrieval hints. These are optional organization hints, not mandatory DDD terminology. Durable syntheses should usually have source evidence or active source provenance relations. ## Good memory examples [Section titled “Good memory 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. * Good user-stated context: `source.user-context-hybrid-memory` records durable product direction stated by the user in the task, without saving private or unrelated preferences. * Good roadmap memory: `synthesis.roadmap` lists current milestones and has `documents` links to issue or docs sources. * Good feature removal: mark `concept.old-feature` stale or supersede it with the replacement feature, and update `synthesis.feature-map`. Bad memory examples include task diaries, private logs, secrets, speculation, temporary implementation notes, and instructions that ask future agents to ignore current code or user requests. * Bad duplicate creation: creating a second memory for the same durable claim instead of updating, marking stale, or superseding the existing one. * Bad task diary: saving “I changed three files and ran tests” when Git history already records the work. * Bad speculation: saving guesses that are not supported by current evidence. * Bad no-value save: creating a memory patch only to say that nothing important happened. ## Bootstrap and suggestion packets [Section titled “Bootstrap and suggestion packets”](#bootstrap-and-suggestion-packets) Use `aictx setup` for guided first-run onboarding. If loaded memory only contains starter placeholders, treat setup, onboarding, and “why is memory empty?” requests as enough context to run the bootstrap workflow proactively. ```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 ``` Use `aictx suggest --from-diff --json` when current code changes need a memory suggestion packet before deciding what durable memory to save. Use `aictx audit --json` to find grouped, actionable memory hygiene issues. During setup, capture explicit product features with the `product-feature` facet when needed. Prefer source-backed syntheses 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/).

# CLI guide

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

# CLI guide [Section titled “CLI guide”](#cli-guide) The CLI is the default path for routine Aictx work. MCP is supported only when the agent client has already launched and connected to `aictx-mcp`. All CLI commands render human-readable output by default. Add `--json` for the shared response envelope: ```bash aictx check --json ``` ## Setup and maintenance [Section titled “Setup and maintenance”](#setup-and-maintenance) ```bash aictx init aictx setup aictx check aictx rebuild aictx reset ``` * `init` creates `.aictx/` and optional repo-level agent guidance. * `setup` guides first-run onboarding and bootstrap memory preview. * `check` validates canonical memory and generated index health. * `rebuild` regenerates indexes from canonical memory. * `reset` backs up and clears local `.aictx/` storage. ## Routine memory work [Section titled “Routine memory work”](#routine-memory-work) ```bash aictx load "change auth routes" aictx suggest --after-task "change auth routes" --json aictx audit --json aictx save --stdin aictx search "auth route conventions" ``` Load narrowly before non-trivial work. Save only durable knowledge directly as active memory. Saving nothing is valid when the task produced no durable future value. ## Inspection and debugging [Section titled “Inspection and debugging”](#inspection-and-debugging) ```bash aictx inspect <id> aictx stale aictx graph <id> ``` Use these commands to inspect one memory object, list stale/superseded memory, or view a one-hop relation neighborhood. ## 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 and viewer [Section titled “Export and viewer”](#export-and-viewer) ```bash aictx export obsidian aictx projects list aictx view --open ``` `aictx view` starts a local, read-only memory viewer. It is CLI-only in v1. CLI-only capabilities are not MCP parity gaps. ## Documentation [Section titled “Documentation”](#documentation) ```bash aictx docs aictx docs getting-started aictx docs demand-driven-memory aictx docs agent-integration --open ``` `aictx docs` lists bundled public docs topics. `aictx docs <topic>` prints the bundled Markdown for that topic. Use `--open` to open the hosted docs site.

# Demand-driven memory

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

# Demand-driven memory [Section titled “Demand-driven memory”](#demand-driven-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, treat that as evidence that project memory may need repair. 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) Repair memory when a task 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. ## Repair with existing primitives [Section titled “Repair with existing primitives”](#repair-with-existing-primitives) Use existing Aictx objects before inventing anything new: * `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. ## Keep it local-first [Section titled “Keep it local-first”](#keep-it-local-first) Demand-driven memory is not broad enterprise ingestion. Aictx should improve local memory quality before adding external inputs such as Slack, Jira, Confluence, hosted sync, embeddings, background scanners, or expert graphs.

# Getting started

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

# Getting started [Section titled “Getting started”](#getting-started) Aictx works inside an existing project. It writes local, reviewable memory files under `.aictx/` and keeps generated indexes separate from canonical memory. ## Requirements [Section titled “Requirements”](#requirements) Aictx requires Node.js `>=22`. ## 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. You do not need to add Aictx to each project’s `package.json` unless that project should pin its own Aictx version. For project-local version pinning: ```bash pnpm add -D @aictx/memory npm install -D @aictx/memory ``` If `aictx` is not on `PATH`, run the same 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) Run this once at the project root: ```bash aictx init ``` By default, init creates `.aictx/` and updates marked Aictx sections in `AGENTS.md` and `CLAUDE.md` so coding agents are told to load memory before non-trivial work and save durable memory after meaningful work. Use `--no-agent-guidance` when you do not want those repo instruction files updated. ## First memory loop [Section titled “First memory loop”](#first-memory-loop) Load relevant project memory before non-trivial work: ```bash aictx load "change auth routes" ``` Do the task. When the work creates durable knowledge future agents should know, save a structured patch: ```bash aictx save --stdin ``` Saved memory is active immediately after Aictx validates and writes the patch. Inspect it asynchronously when needed: ```bash aictx view aictx diff ``` Aictx writes local files and never commits automatically. ## Guided setup [Section titled “Guided setup”](#guided-setup) For first-run onboarding: ```bash aictx setup aictx setup --apply ``` Use `aictx setup` when you want a guided bootstrap preview. Use `aictx setup --apply` when the conservative bootstrap memory patch should be applied immediately.

# MCP guide

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

# MCP guide [Section titled “MCP guide”](#mcp-guide) `aictx-mcp` is an MCP stdio server. The MCP client must launch it and connect to its stdin/stdout. An agent generally cannot start `aictx-mcp` in a shell and then use it as MCP tools in an already-running session. ## Install [Section titled “Install”](#install) The simplest setup is a global install: ```bash npm install -g @aictx/memory ``` Configure your MCP client to launch: ```bash aictx-mcp ``` If `aictx-mcp` is not on `PATH`, configure the client to launch it through the project package manager or local binary path: ```bash pnpm exec aictx-mcp npm exec aictx-mcp ./node_modules/.bin/aictx-mcp npx --package @aictx/memory -- aictx-mcp ``` ## Tools [Section titled “Tools”](#tools) MCP exposes exactly these tools in v1: * `load_memory` * `search_memory` * `save_memory_patch` * `diff_memory` Use MCP equivalents only when the client already exposes Aictx MCP tools: ```text load_memory({ task: "<task summary>", mode: "coding" }) search_memory({ query: "auth route conventions" }) save_memory_patch({ patch: { source, changes } }) diff_memory({}) ``` If the MCP server was launched globally rather than from the project root, pass the target root explicitly: ```text load_memory({ project_root: "/path/to/project", task: "<task summary>", mode: "coding" }) ``` ## CLI-only boundaries [Section titled “CLI-only boundaries”](#cli-only-boundaries) The CLI remains the supported path for setup, maintenance, recovery, export, inspection, registry management, local viewing, suggestion, and audit operations. CLI-only capabilities are not MCP parity gaps. Do not add or ask for MCP tools solely to mirror these CLI commands. In particular, do not add `aictx view` to MCP. Local viewing is a browser inspection surface, not a routine MCP memory operation.

# Mental model

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

# Mental model [Section titled “Mental model”](#mental-model) Aictx is a memory discipline system, not just a storage folder. The product goal is simple: future agents should not restart from zero when working in a project. They should load the durable context that matters, do the task, and save only reusable knowledge that future agents can safely rely on. ## Canonical memory [Section titled “Canonical memory”](#canonical-memory) `.aictx/` contains canonical memory and generated support files. Canonical memory is the durable source of truth. It 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. Do not hand-edit generated state when a supported Aictx command can produce it. ## 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`. Do not create `history`, `task-note`, or `feature` object types. Use Git, events, and object statuses for history; branch or task scope for temporary task context; and `concept` or `synthesis` facets for product capabilities. ## Demand-driven memory quality [Section titled “Demand-driven memory quality”](#demand-driven-memory-quality) Use real work to improve memory. 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. ## Async inspection [Section titled “Async inspection”](#async-inspection) Aictx writes inspectable files. Use the local viewer or, in Git projects, the memory diff: ```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.

# Reference

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

# Reference [Section titled “Reference”](#reference) ## CLI commands [Section titled “CLI commands”](#cli-commands) | 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` | Use `--json` on commands that support structured output: ```bash aictx check --json aictx docs --json ``` ## MCP tools [Section titled “MCP tools”](#mcp-tools) MCP exposes exactly: * `load_memory` * `search_memory` * `save_memory_patch` * `diff_memory` CLI-only capabilities are not MCP parity gaps. ## Docs command [Section titled “Docs command”](#docs-command) ```bash aictx docs aictx docs getting-started 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`. Do not create `history`, `task-note`, or `feature` 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`. Save only durable information future agents should know. Save nothing when the task produced no durable future value.

# Troubleshooting

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

# Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ## `aictx` is not on PATH [Section titled “aictx is not on PATH”](#aictx-is-not-on-path) Use the package-manager or local-binary form: ```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` does not start MCP. Configure your MCP client 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. If MCP tools are not available, stay on the CLI path. ## 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. Run: ```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 ``` ## Schema or index errors [Section titled “Schema or index errors”](#schema-or-index-errors) Validate storage: ```bash aictx check ``` Rebuild generated indexes: ```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) Use: ```bash aictx diff ``` Plain `git diff -- .aictx/` can omit untracked memory files before staging.

# Local viewer

> Use the read-only local browser viewer to inspect project memory.

# Local viewer [Section titled “Local viewer”](#local-viewer) `aictx view` starts a local, read-only browser viewer for human inspection. ```bash aictx view aictx view --open aictx view --port 4888 aictx view --json ``` 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. Use: ```bash aictx projects list aictx projects add aictx projects add /path/to/project aictx projects remove <registry-id|project-id|path> aictx projects prune ``` ## 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. CLI-only capabilities are not MCP parity gaps. Do not add `aictx view` to MCP.