Hindsight — Agent Plugin

A portable Agent Plugin (spec 1.0.0) that gives any compatible agent client long-term memory via Hindsight.

Agent Plugins is the vendor-neutral standard (AWS, Cursor, GitHub/Microsoft, OpenAI, Vercel) for packaging Agent Skills + MCP servers into one distributable plugin. At launch it is supported by ChatGPT/Codex, Cursor, GitHub Copilot, Kiro, and VS Code.

Codex users: Codex's Agent Plugins loader drops this plugin's Authorization header, so it cannot authenticate. Use the Coding Agents integration instead; see Codex below.

This is the portable front door to Hindsight: one artifact, every supported client. It carries the same retain / recall / reflect memory as our per-IDE integrations, but as a single standards-based bundle instead of N hand-rolled configs.

What's in the bundle

agent-plugin/
├── plugin.json                       # manifest ($schema + name + metadata)
├── mcp.json                          # Hindsight MCP server (Streamable HTTP)
└── skills/
    └── hindsight-memory/
        └── SKILL.md                  # teaches the agent when to recall/retain/reflect

• mcp.json points the client at Hindsight's built-in MCP server (retain, recall, reflect, knowledge pages, and more — see MCP Server docs). The plugin is transport-only; all memory logic stays server-side.
• skills/hindsight-memory/SKILL.md is loaded into the agent's context so it knows when to reach for memory, not just that the tools exist.

Configuration

The plugin reads two environment variables (values are interpolated into mcp.json):

Self-hosting: replace the host in mcp.json (https://api.hindsight.vectorize.io) with your deployment's URL. A local server with the MCP endpoint open needs no API key.

Env-var interpolation syntax varies by client. Most use ${VAR}; some (VS Code, Cursor) prefer ${env:VAR}. If your client doesn't substitute, paste the literal key and bank id into mcp.json instead. This does not work in Codex, which removes the Authorization header regardless of its value (see Codex).

Bank selection when HINDSIGHT_BANK_ID is unset. A client that substitutes variables sends an empty X-Bank-Id, and the server uses the default bank. A client that does not substitute sends the literal text ${HINDSIGHT_BANK_ID}, which Hindsight treats as a bank name: reads fail with bank-not-found, and the first retain creates a bank with that name. Set the variable, or paste the bank id literally, to avoid this.

Install

Installation and distribution are intentionally left to each client by the spec. Common paths:

• VS Code / GitHub Copilot / Cursor / Kiro — add this plugin directory through the client's plugin/MCP UI, or drop it where the client discovers plugins, then set the two environment variables above.
• Codex — not supported by this plugin; see Codex.
• ChatGPT — register the plugin per the client's Agent Plugins support.

Once installed, ask the agent something that depends on past context (or tell it a durable preference) and it will call recall / retain automatically, guided by the skill.

Codex

Codex's Agent Plugins loader treats Authorization as a header only the client may set, so it removes the one in this plugin's mcp.json. It also copies the other headers verbatim, without expanding ${VAR} placeholders. The portable plugin therefore cannot authenticate to Hindsight Cloud from Codex, and pasting a literal key into mcp.json does not help because the header is removed whatever its value.

For Codex, use the Coding Agents integration instead. It writes Codex's native MCP configuration and adds the automatic recall/retain hooks:

npx @vectorize-io/hindsight-coding-agents install codex

Want automatic capture (hooks)?

Agent Plugins 1.0.0 standardizes Skills + MCP, not session lifecycle hooks. This plugin therefore delivers explicit, tool-driven memory that works identically everywhere. For the fully automatic experience — recall injected before every prompt and transcripts retained on session end — use the hook-based Coding Agents integration, which covers Claude Code, Codex and many other coding agents. The two share the same banks, so memory captured by one is recalled by the other.

Validate the manifests

python3 hindsight-integrations/agent-plugin/validate.py

Checks that plugin.json and mcp.json parse and satisfy the Agent Plugins 1.0.0 required-field contract.