Aictx

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 durable project facts, decisions, warnings, workflows, source records, and syntheses under .aictx/ as reviewable local files, indexes them locally for fast retrieval, and keeps them compatible with Git workflows.

load relevant memory -> do work -> save durable memory

Aictx does not require a cloud account, embeddings, hosted sync, an external model API, or network access for core memory commands. Saved memory is active immediately after Aictx validates and writes it, and Aictx never commits for you.

This repository publishes the npm package @aictx/memory. It is unrelated to similarly named packages in other ecosystems.

Why Aictx?

Aictx is for durable project context that should survive between agents, sessions, branches, and reviews.

• Why not AGENTS.md only? Agent instruction files are good operating manuals, but they become too broad and static when they also try to hold product intent, decisions, gotchas, workflows, and source-backed summaries.
• Why not a vector DB or RAG stack? Those are useful for large retrieval systems. Aictx keeps v1 project memory local, inspectable, Git-aware, and usable without embeddings, hosted infrastructure, or a model API.
• Why not long context? Long context helps inside one session. It does not make memory reviewable, current, reusable across future sessions, or easy to clean up when facts go stale.
• Why local files? Plain files are reviewable and portable. Aictx builds on that foundation with validation, typed memory, a local index, task-focused loading, relation-aware inspection, and a save/no-save discipline.

Documentation

The landing page lives at aictx.dev. Public docs live at docs.aictx.dev.

Good starting points:

• Getting started
• Capabilities
• Specializing Aictx
• Agent integration
• Agent recipes

Bundled docs are also available from the CLI:

aictx docs
aictx docs getting-started
aictx docs capabilities
aictx docs agent-integration --open
aictx docs agent-recipes

Install

Aictx requires Node.js >=22.

Install globally for the simplest CLI and MCP setup:

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:

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

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

pnpm exec aictx init
npm exec aictx init
./node_modules/.bin/aictx init
npx --package @aictx/memory -- aictx init

For MCP fallbacks:

pnpm exec aictx-mcp
npm exec aictx-mcp
./node_modules/.bin/aictx-mcp
npx --package @aictx/memory -- aictx-mcp

Package-manager and local-binary fallbacks are version-sensitive. If a local install is stale, update it or use a current global/source binary before trusting schema errors.

Quickstart

Initialize memory storage inside an existing project:

aictx init

For first-run onboarding:

aictx setup
aictx setup --apply

Load relevant memory before non-trivial work:

aictx load "change auth routes"

Save durable memory after meaningful work:

aictx remember --stdin

Inspect memory asynchronously when needed:

aictx view
aictx diff

Aictx writes local files and never commits automatically.

Mental model

.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. Generated state is rebuildable: the SQLite search index, context packs, and exports can be regenerated from canonical memory.

Aictx storage uses a hybrid memory model:

• source records preserve where context came from.
• Atomic memories capture precise reusable claims as decision, constraint, question, fact, gotcha, workflow, note, or concept objects.
• synthesis records maintain compact summaries for product intent, feature maps, roadmap, architecture, conventions, agent guidance, and repeated workflows or how-to collections.

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.

Load modes are coding, debugging, review, architecture, and onboarding. Modes tune deterministic ranking and rendering only; they do not broaden the project scope, call a model, use external retrieval, or load the whole project.

CLI and MCP boundary

The CLI is the default path for routine memory work. MCP remains a supported integration path when the agent client has already launched and connected to aictx-mcp.

MCP exposes exactly load_memory, search_memory, inspect_memory, remember_memory, save_memory_patch, and diff_memory in v1.

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

Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows remain outside local MCP. CLI-only capabilities are not MCP parity gaps. Do not add or ask for MCP tools solely to mirror these CLI commands, and do not edit .aictx/ files directly when a supported MCP tool or CLI command exists.

aictx view [--port <number>] [--open] [--detach] [--json] starts the local read-only memory viewer. aictx view is CLI-only in v1.

Agent memory discipline

Agents should:

• 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.

Right-size memory. Use atomic memories for precise reusable claims, synthesis memories for compact area-level understanding, and source memories to preserve where context came from. Create relations only when the connection matters, using predicates such as derived_from, summarizes, documents, requires, depends_on, affects, or supersedes.

Use update_object, mark_stale, supersede_object, delete_object, and create_relation when they fit better than creating another object. Use gotcha for known failure modes and traps. Use workflow for repeated project-specific how-tos: procedures, runbooks, command sequences, release/debugging/migration paths, verification routines, and maintenance steps. Generic tutorials, one-off task notes, and task diaries should not become workflow memory.

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.

Development

pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm test:local
pnpm build:docs

The package provides two binaries:

• aictx: the command-line interface
• aictx-mcp: the MCP stdio server for AI coding clients

For contribution workflow, branch protection, and AI-agent git instructions, see CONTRIBUTING.md. The short version is: work on a feature branch, open a pull request to main, wait for required checks, then merge the pull request instead of pushing directly to main.

Project health

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support paths: SUPPORT.md
• Public roadmap: ROADMAP.md
• Release policy: RELEASE.md
• Changelog: CHANGELOG.md

Public releases should have matching vX.Y.Z Git tags and npm provenance. The default branch is protected and requires pull requests plus CI/security checks before merge.

AI-agent setup prompt

Copy and paste this prompt into an AI coding agent to set up a repository:

Set up fresh Aictx memory for this Aictx source repository.

First reinstall the current Aictx package globally:
npm install -g @aictx/memory@0.1.30

Then reset the local `.aictx/` state with the Aictx CLI:
aictx reset

Run the initial onboarding and apply the conservative bootstrap memory patch:
aictx setup --apply --force

Finally, run:
aictx check

Inspect the accepted memory later with aictx view or aictx diff when needed.