Skip to content
Aictx

MCP guide

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.

Install

Section titled “Install”

A global install gives the simplest setup:

Terminal window
npm install -g @aictx/memory

The MCP client can launch the global binary:

Terminal window
aictx-mcp

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

Terminal window
pnpm exec aictx-mcp
npm exec aictx-mcp

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

Terminal window
npx --package @aictx/memory -- aictx-mcp

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

Terminal window
./node_modules/.bin/aictx-mcp

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

Tools

Section titled “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:

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:

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”

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.