atomicmemory-integrations

Plugins, adapters, and the shared MCP server that expose AtomicMemory to coding agents and AI frameworks.

What's inside

packages/
└── mcp-server/              # @atomicmemory/mcp-server — the spine
                             # exposes memory_search / memory_ingest / memory_package
                             # over MCP, wraps @atomicmemory/atomicmemory-sdk

plugins/                     # coding-agent wrappers
├── claude-code/             # Claude Code plugin (plugin.json + SKILL.md)
├── codex/                   # Codex plugin (manifest + MCP config + SKILL.md)
└── openclaw/                # OpenClaw plugin (openclaw.plugin.json + skill.yaml)

examples/                    # runnable examples (coming soon)

Framework adapters (adapters/vercel-ai-sdk, adapters/langchain-js, adapters/mastra, adapters/openai-agents, adapters/langgraph-js) are tracked as planned work — see the docs site at https://docs.atomicmemory.ai/integrations/ for status.

Architecture

All coding-agent plugins are thin wrappers over the same @atomicmemory/mcp-server process. The shared MCP surface exposes memory_search, memory_package, and memory_ingest with extraction modes (text, messages) plus deterministic one-record snapshots (verbatim). A plugin's job is:

1. Ship the agent-facing skill/manifest in the shape that agent expects.
2. Tell the agent how to spawn the MCP server with the user's config.
3. Nothing else.

Memory semantics live in @atomicmemory/atomicmemory-sdk; storage and retrieval live in atomicmemory-core. Plugins in this repo do not re-implement memory — they adapt the surface.

Develop

pnpm install
pnpm build
pnpm test

Codebase analysis

This repo uses Fallow for dead-code, duplication, and complexity analysis.

pnpm fallow            # full analysis
pnpm fallow:audit      # changed-file audit for PR/agent review
pnpm fallow:dead-code  # unused files/exports/dependencies
pnpm fallow:dupes      # duplicated code
pnpm fallow:health     # complexity and maintainability

Fallow is configured in .fallowrc.json. The .fallow/ cache directory is intentionally ignored.

Install, update, and verify local plugins

These integrations are source-only right now. Updating the repo does not automatically update an installed agent plugin. Rebuild the MCP server, refresh the agent plugin install, then restart the host agent so it reloads hook and MCP configuration.

1. Rebuild after source changes

Build the SDK first if it changed, then rebuild this repo:

cd ../atomicmemory-sdk
pnpm build

cd ../atomicmemory-integrations
pnpm --filter @atomicmemory/mcp-server build
pnpm build

ATOMICMEMORY_MCP_SERVER_BIN must point at the rebuilt file:

export ATOMICMEMORY_MCP_SERVER_BIN="$PWD/packages/mcp-server/dist/bin.js"
test -f "$ATOMICMEMORY_MCP_SERVER_BIN"

Version bump helper

Use the repo helper whenever plugin-facing files change:

# Verify Claude, Codex, and OpenClaw plugin versions are aligned:
pnpm check:plugin-versions

# Bump all plugin versions by semver:
pnpm bump:plugin-versions patch
pnpm bump:plugin-versions minor
pnpm bump:plugin-versions major

# Or set an explicit version:
pnpm bump:plugin-versions 0.1.2

The helper updates every version field used by the current plugin manifests, packages, skills, and Claude marketplace metadata.

2. Claude Code

Claude Code updates are version-gated. If hook scripts, hooks.json, .claude-plugin/plugin.json, skills, or marketplace metadata change, bump the plugin versions with pnpm bump:plugin-versions <patch|minor|major|x.y.z> before asking users to run claude plugin update. For Claude, the helper keeps these fields in sync:

• .claude-plugin/marketplace.json at /plugins/*/version
• plugins/claude-code/.claude-plugin/plugin.json at /version
• plugins/claude-code/package.json at /version

If the Claude version stays unchanged, claude plugin update claude-code@atomicmemory can correctly report "already at the latest version" while its installed cache still contains older files.

Make sure Claude's marketplace points at this checkout:

claude plugin marketplace list

If atomicmemory points at an old clone, replace it:

claude plugin marketplace remove atomicmemory
claude plugin marketplace add ./ --scope user

Install or refresh the plugin cache:

# If the plugin is not installed yet:
claude plugin install claude-code@atomicmemory

# If the plugin is already installed:
claude plugin update claude-code@atomicmemory

Then fully restart Claude Code. Running Claude sessions can keep the previous hook registration in memory. Do not treat ~/.claude/plugins/cache/... as the source of truth; it is only Claude's installed cache.

Required env before launching Claude Code:

export ATOMICMEMORY_API_URL="https://memory.yourco.com"
export ATOMICMEMORY_API_KEY="am_live_..."
export ATOMICMEMORY_PROVIDER="atomicmemory"
export ATOMICMEMORY_SCOPE_USER="$USER"
export ATOMICMEMORY_CAPTURE_LEVEL="balanced"

Smoke-test the installed PreCompact hook. It should print nothing and exit 0:

PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/atomicmemory/claude-code/* | head -n 1)
printf '{"trigger":"manual","session_id":"smoke"}' \
  | bash "$PLUGIN_ROOT/scripts/on_pre_compact.sh"

In Claude Code, verify:

• claude plugin list shows claude-code@atomicmemory enabled.
• /compact is not blocked by PreCompact.
• A new session can see memory_search, memory_ingest, and memory_package.

3. Codex

The Codex plugin is configuration-only, but it still points at the built MCP server. After changing .codex-mcp.json, skills, or the MCP server:

pnpm --filter @atomicmemory/mcp-server build

Run pnpm bump:plugin-versions <patch|minor|major|x.y.z> when .codex-plugin/plugin.json, .codex-mcp.json, skills, or marketplace metadata change. For Codex, the helper keeps these fields in sync:

• plugins/codex/.codex-plugin/plugin.json at /version
• plugins/codex/package.json at /version
• plugins/codex/skills/atomicmemory/SKILL.md at /metadata/version

The Codex marketplace entry does not carry a plugin version; the plugin manifest and skill metadata are the source of truth.

Restart Codex or reinstall the local plugin from the repo/personal marketplace so it reloads .codex-mcp.json and SKILL.md. Verify ATOMICMEMORY_MCP_SERVER_BIN, ATOMICMEMORY_API_URL, ATOMICMEMORY_API_KEY, ATOMICMEMORY_PROVIDER, and at least one ATOMICMEMORY_SCOPE_* env var are visible to Codex.

4. OpenClaw

After changing OpenClaw plugin code or the shared MCP server:

pnpm --filter @atomicmemory/mcp-server build
pnpm --filter @atomicmemory/openclaw-plugin build

cd plugins/openclaw
claw plugin install .

Run pnpm bump:plugin-versions <patch|minor|major|x.y.z> when openclaw.plugin.json, skill instructions, package metadata, or provider registration changes. For OpenClaw, the helper keeps these fields in sync:

• plugins/openclaw/openclaw.plugin.json at /version
• plugins/openclaw/package.json at /version
• plugins/openclaw/skills/atomicmemory/skill.yaml at /version

Restart the OpenClaw host if it keeps plugin modules loaded. Verify the plugin registers atomicmemory.memory and that config includes apiUrl, apiKey, provider, and scope.user.

License

Apache-2.0.