@agentimprint/mcp

Cross-harness MCP server for AgentImprint — sovereign, encrypted memory for AI agents. Install it once and every MCP-compatible harness (Claude Code, Cursor, Codex, OpenClaw, Hermes, and others) gains six tools to store, recall, list, and export agent memories, with your choice of key custody.

Quick Install (any MCP harness)

Add the following to your harness MCP configuration file:

{
  "mcpServers": {
    "agentimprint": {
      "command": "npx",
      "args": ["-y", "@agentimprint/mcp"],
      "env": { "AGENTIMPRINT_API_KEY": "<optional — omit to self-bootstrap>" }
    }
  }
}

No pre-install required — npx pulls the package on first use.

The Six Tools

| Tool | What it does | |---|---| | imprint_status | Reports current credential mode, vault UUID, custody type, and any active warnings. | | imprint_bootstrap | Provisions a new agent identity and vault. For sovereign/passphrase custody the key is written to a local 0600 file (never returned in the response). | | imprint_remember | Encrypts and stores a memory note's content; metadata (tags, domain, type) is stored in cleartext for querying. | | imprint_recall | Decrypts and retrieves memories matching a query or tag filter. | | imprint_list | Lists memory metadata (uuid, entry_type, is_encrypted, tags, domain, created_at) without decrypting content. | | imprint_export | Exports the full vault as a Merkle-signed JSON bundle for backup or migration. |

What is and isn't encrypted. Only a memory's content is end-to-end encrypted (AES-256-GCM, per-entry derived key, decryptable only with your master key). Metadata — entry_type, tags, domain, confidence, and timestamps — is stored in cleartext so the server can filter and paginate recall/list. Treat tags and domain as visible to the server: do not put secrets in them.

Metadata is also not authenticated: it is stored alongside the ciphertext, not bound into it, so a compromised backend could relabel or mutate it (e.g. retag an old memory to match a sensitive query) without breaking decryption. Don't make trust or safety decisions on metadata alone. recall further quarantines any entry the server reports as not encrypted — it is returned flagged (untrusted_unencrypted) with its content withheld, because such content was never authenticated under your key and could be backend-injected. Authenticated metadata (AES-GCM AAD binding) and full metadata encryption are planned opt-ins.

Credential Modes

BYO API Key

Set AGENTIMPRINT_API_KEY in the MCP server env block. The server uses this key for all API calls. You may also set AGENTIMPRINT_MASTER_KEY, AGENTIMPRINT_AGENT_UUID, and AGENTIMPRINT_VAULT_UUID to wire up an existing vault without bootstrapping.

Self-Bootstrap

Omit AGENTIMPRINT_API_KEY. On first use, call imprint_bootstrap — the server registers a new agent, creates a vault, and persists credentials to ~/.agentimprint/credentials.json (mode 0600). Subsequent calls load from that file automatically.

Custody Modes

Three custody options control where the master encryption key lives:

managed (default)

The master key is generated locally and stored in ~/.agentimprint/credentials.json. Convenient — no extra steps required.

WARNING — Single Point of Failure: Under managed custody the master key lives on this host with NO escrow backstop in v1. If the credentials file is lost the vault cannot be decrypted. Back it up (e.g. copy to a password manager) or switch to sovereign or passphrase custody. Recovery escrow is a v1.1 fast-follow.

sovereign

Pass custody: "sovereign" to imprint_bootstrap. The master key is generated locally, written to a 0600 file at ~/.agentimprint/sovereign-key-<vaultUuid>.txt, and is never stored in credentials and never returned in the tool response (a tool result transits the model/provider — the key must not). The bootstrap response returns only the file path. Read the file, save the key securely, then set AGENTIMPRINT_MASTER_KEY to use the vault.

{ "custody": "sovereign" }

passphrase

Pass custody: "passphrase" to imprint_bootstrap and supply the passphrase via the AGENTIMPRINT_PASSPHRASE environment variable — never as a tool argument (which would transit the model/provider). The master key is derived deterministically via scrypt (cost N=2¹⁷) from the passphrase and your creator_identifier (used as a per-identity salt, so identical passphrases across different agents don't collide), and is never stored by the server.

{ "custody": "passphrase", "creator_identifier": "cooper" }

Like sovereign custody, the derived key is written to the 0600 file (not returned). To use the vault in later sessions, supply that key via AGENTIMPRINT_MASTER_KEY — remember/recall do not re-derive it. You can reproduce the same key any time from the same passphrase and the same creator_identifier with the same scrypt parameters.

Per-Harness Placement

Claude Code

Option A — project scope (.mcp.json in project root):

{
  "mcpServers": {
    "agentimprint": {
      "command": "npx",
      "args": ["-y", "@agentimprint/mcp"]
    }
  }
}

Option B — global scope via CLI:

claude mcp add agentimprint -- npx -y @agentimprint/mcp

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "agentimprint": {
      "command": "npx",
      "args": ["-y", "@agentimprint/mcp"]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[[mcp_servers]]
name = "agentimprint"
command = "npx"
args = ["-y", "@agentimprint/mcp"]

OpenClaw

Install via ClawHub or place the plugin/ directory from this repo into your OpenClaw plugins folder. The plugin/.mcp.json wires the MCP server automatically.

Hermes

Add to your Hermes MCP configuration under mcp_servers:

{
  "mcp_servers": {
    "agentimprint": {
      "command": "npx",
      "args": ["-y", "@agentimprint/mcp"]
    }
  }
}

Environment Variables

| Variable | Default | Purpose | |---|---|---| | AGENTIMPRINT_API_KEY | (none) | BYO API key; omit to use self-bootstrap flow. | | AGENTIMPRINT_BASE_URL | https://api.agentimprint.io | Override API endpoint (e.g. for self-hosted). | | AGENTIMPRINT_HOME | ~/.agentimprint | Directory for credentials.json and local state. | | AGENTIMPRINT_MASTER_KEY | (none) | Supply a sovereign/passphrase master key (64 hex chars) at runtime. | | AGENTIMPRINT_PASSPHRASE | (none) | Passphrase for passphrase custody at bootstrap (never passed as a tool argument). | | AGENTIMPRINT_AGENT_UUID | (none) | Override agent UUID (BYO sovereign vault wiring). | | AGENTIMPRINT_VAULT_UUID | (none) | Override vault UUID (BYO sovereign vault wiring). |

License

MIT — see LICENSE.