Agent integrations¶

An integration is the glue that helps a coding agent use MemCastle at the lifecycle points the agent exposes. Pi and OpenCode can load wake-up context and write automatic checkpoints; Claude Code and Codex have documented gaps and manual fallbacks. It decides when to call MemCastle and does nothing else; every call goes to the daemon over MCP and HTTP. The Integration contract specifies full lifecycle conformance. This page is about getting one onto your machine.

Pi, OpenCode, Claude Code and Codex integrations are independently distributed provider plugins. memcastle integration installs any of them locally, after its provider plugin is available. An installed provider plugin needs no npm download on the user's machine. plugin install only makes it selectable; integration install <module-id> still copies and registers the selected agent-side files locally, and integration remove undoes that registration without uninstalling its parent plugin.

flowchart LR
    subgraph machine[Your machine]
        A[Agent: Pi, OpenCode, Claude Code or Codex] -->|loads| I[Installed integration]
        I -->|MCP and HTTP| D[memcastle daemon]
        I -.->|exposes| S[Skills it names]
    end
    P[Core assets or installed plugin] -->|memcastle integration install| I

What an integration packages¶

An integration is the complete agent-facing MemCastle package for one agent. MCP and skills stay usable on their own, with no integration installed:

flowchart TB
    M[MemCastle]
    M --> MCP[MCP<br/>standalone: any MCP client]
    M --> SK[Skills<br/>standalone: copied into any client]
    M --> INT[Integration]
    INT --> L[Lifecycle hooks and configuration]
    INT --> IS[Skills it exposes]
    INT --> A[Agent-specific assets]
    IS -.->|by name| SK

• MCP needs no integration: MCP clients connect to the daemon directly.
• Skills need no integration either: Install the skills copies them into the directory a client scans.
• An integration adds the lifecycle glue, and carries the skills the agent should have, so memcastle integration install pi installs both Pi's extension and its skills after the plugin is installed. Its manifest lists them, each either a shared skill referenced by name or a skill of its own.

Supported integrations¶

The integration protocol supports 0.4 and later, but the installation steps below require a Core build with plugin install (for example, 0.5 or the current prerelease); stable 0.4.1 cannot install provider plugins. memcastle integration list shows installed plugin integrations alongside those Core ships, with their own version ranges.

Requirements¶

• The agent is installed and its command (pi, opencode, claude, codex) is on your PATH. The installer runs it to read its version and, for Pi, to register the integration with it.
• Install the integration's provider plugin first (see Where integrations come from). Core ships no agent-specific integration assets.
• The agent and MemCastle versions are inside the ranges the integration declares. The installer refuses otherwise, before it writes anything, and tells you which version it found.

You do not need bun, node or npm: plugin integrations already contain their runtime or declarative assets. The daemon does not have to be running to install one; it has to be running when the agent uses it.

Install¶

memcastle integration list
memcastle plugin install anthropic
memcastle integration install claude-code
# For Codex, first install memcastle-openai (see the Codex guide), then:
memcastle integration install codex
# For Pi, first install its provider archive (see the Pi guide), then:
memcastle integration install pi
# For OpenCode, first install its provider archive (see the OpenCode guide), then:
memcastle integration install opencode

install does five things, in this order, and stops at the first one that fails:

1. Finds the integration among the shipped ones or installed plugins and checks it against your MemCastle and agent.
2. Copies its files, and the skills its manifest names, to ~/.local/share/memcastle/agents/<id>/.
3. Records what it copied, with a SHA-256 for each file, in a receipt beside them.
4. Tells the agent about the copy: pi install for Pi, one plugin file for OpenCode, or the agent's local marketplace for Claude Code and Codex.
5. Checks the result: the entry file is there, and the agent knows the copy.

It reports every change it made. If the registration fails, the copy is removed again, and an earlier version that was installed is put back.

Running install again is safe. When the installed copy is already what the package ships and the agent still knows it, nothing is touched and the command says so. When it is not (the package was upgraded, a file was edited, the agent forgot it), install repairs it.

The copy is yours, not the package's. Upgrading or removing the MemCastle package never changes an installed integration, and an installed integration keeps working if the package that shipped it is gone.

What is installed, and what is left alone¶

~/.local/share and ~/.config are the defaults; XDG_DATA_HOME, XDG_CONFIG_HOME and, for OpenCode, OPENCODE_CONFIG_DIR move them.

Everything else in the agent's configuration is left exactly as it was:

• MemCastle never edits Pi's settings.json itself. Pi does, through pi install and pi remove, so the packages you already have stay.
• MemCastle never opens opencode.json and never adds an mcp.memcastle entry. The plugin connects to the daemon itself, and an MCP entry next to it would list every tool twice.
• MemCastle never opens a Claude Code settings file. It uses claude plugin marketplace add, claude plugin install, and their matching removal commands.
• MemCastle never edits Codex's config.toml. Codex owns the marketplace and MCP registration through codex plugin commands.
• A plugins/memcastle.ts that MemCastle did not write is never overwritten or deleted. The installer stops with conflict instead.
• MemCastle never writes your authentication token anywhere. If the daemon requires one, give the agent MEMCASTLE_AUTH_TOKEN in its environment.
• MemCastle never writes into the directories where you keep your own skills (~/.agents/skills, ~/.claude/skills, ...). The skills of an integration live inside its installed copy, and the agent is told to read them from there. A skill of yours with the same name as one of the integration's is the one the agent uses.

Configure¶

Pi and OpenCode read their settings from the environment (and OpenCode also reads plugin options). Codex uses the memcastle-openai plugin's MCP declaration at http://127.0.0.1:8420/mcp and reads a token from MEMCASTLE_AUTH_TOKEN. None of these integrations stores a token in files that install writes. The variables are listed in each guide: Pi, OpenCode, and Codex.

Update¶

memcastle integration list
memcastle integration update pi

list marks an integration outdated when the package ships a different version, or different files, than the ones installed. update installs what the package ships now, and tells you it was already current when it was. It is install for something already installed; it refuses an integration that was never installed (not_installed), so a typo cannot add one.

After an upgrade of MemCastle, run memcastle integration list: an integration whose supported MemCastle range no longer includes the new version shows as incompatible, and a new MemCastle that ships a newer integration shows it as outdated. Restart the agent after an update, because it loads the integration when it starts.

Remove¶

memcastle integration remove pi

remove asks the agent to forget the copy, then deletes the copy. It needs neither the package nor the shipped files, so it still works after MemCastle itself was uninstalled, and it works when the agent is gone too (the copy is deleted, and the report says the agent could not be asked). Removing something that is not installed succeeds and says so.

Where integrations come from¶

Core's shared skills live under one assets root, in the same layout in a package and a checkout. Installed provider plugins supply their own integration assets separately:

<assets root>/
├── integrations/
│   └── (no Core-shipped agent integration)
├── skills/                        (the shared skills, referenced by name)
│   └── <name>/SKILL.md
└── sources/                       (the bundled mining sources, see below)

The assets root is the one runtime assets directory, chosen in this order:

1. --assets-dir <dir> on the command, MEMCASTLE_ASSETS_DIR, or assets.dir in the config file. An explicit choice never falls through: a directory that does not exist is an error.
2. The package's share/memcastle next to the executable (/usr/bin/memcastle finds /usr/share/memcastle), then /usr/local/share/memcastle and /usr/share/memcastle.
3. Nothing: a standalone binary still finds integrations in installed provider plugins.

Any of the MemCastle release packages carry the assets root: the tarballs, the .deb and .rpm, the AUR package and the Homebrew formula (see Installation). The standalone tarball memcastle_<version>_integrations.tar.gz holds the empty integrations/ tree and shared skills/.

memcastle integration list prints the assets root it used and how it was chosen, so you can see which of the two you are looking at.

Developing MemCastle¶

To develop an integration, build the archive from its provider checkout and install that plugin into a disposable palace. Core's checkout still holds the shared skills and source-packaging assets:

mise run integrations:package  # package the shared skills
memcastle integration list --assets-dir "$PWD"

MEMCASTLE_ASSETS_DIR does the same as the flag for a whole shell session. In this repository mise.toml sets it to the Core checkout during development. Run the command from another directory to use installed assets, and see Development for what else it sets. mise run integrations:check unsets it and checks that Core packages no agent integration.

mise run integrations:package lays out the shared skills under target/bundled-integrations for a release.

The bundled mining sources use the same root: with --assets-dir pointing at a root whose sources/ holds a source.wasm and a memcastle-source.toml in each directory, the daemon offers those as the bundled sources. A checkout has no such package (its sources/ holds projects, whose component is built into dist/), so the daemon then falls back to the installed ones.

The manifest¶

Each integration is described by memcastle-integration.toml beside its files. Unknown keys are refused, so a typo is an error and not a silently ignored setting.

format = 1

[integration]
id = "pi"
version = "0.1.0"
description = "Wake-up, recall, checkpoint and mining lifecycle for the Pi coding agent"

[compatibility]
memcastle = ">=0.2"
agent = ">=1.0"

[agent]
kind = "pi"
entry = "extension.js"

[[assets]]
from = "dist"
to = "."

[[skills]]
name = "wake-up"

[[skills]]
name = "search-before-answer"

Only the skills a manifest names are installed, and a named skill must have a SKILL.md: a missing one is assets_missing, and nothing is written. Running install again, or update, after a manifest drops a skill removes it from the installed copy. An integration that names no skill installs none. The [skills] table that earlier manifests used (install = true) is refused, and the message says what to write.

What the manifest cannot express, such as how an agent learns about a copy, is the adapter's job, chosen by agent.kind. Adding an agent is a new adapter and a new kind; the manifest format does not change.

How it relates to the rest¶

• The daemon. The integration is a client like any other and finds the daemon the same way the CLI does. Installing needs no daemon, and uses no palace.
• MCP. The integrations speak MCP to the daemon themselves, with the memory mode of the session. There is no MCP tool that installs, updates or removes an integration, so an agent cannot change the code it runs.
• Skills. The wake-up, search-before-answer and checkpoint instructions are the skills of the release. An integration names the ones it exposes, and they are installed inside its copy, so they are the ones written for this MemCastle version and no separate skill installation is needed. The Pi and OpenCode provider integrations expose all five, and their agents list them themselves.
• Mining sources. memcastle-pi and memcastle-opencode have WebAssembly source modules that mine agent session history (Mining sources). The lifecycle integrations on this page are what run inside the agent.

Troubleshooting¶

Every failure names a diagnostic code, and memcastle integration changes nothing on the machine for any of them except validation_failed.

memcastle integration list is the first thing to run: its STATE column says modified when a file changed after installation or the agent no longer knows the copy, and lists what it found under the table. install repairs it.

See also Troubleshooting for codes outside this page, and ADR-034 for why integrations are distributed this way.