kilo-agentmemory-bridge

Kilo/OpenCode plugin bridge for agentmemory.

This project ports agentmemory's Claude Code hook integration to Kilo/OpenCode. The bridge captures Kilo/OpenCode session activity through the @opencode-ai/plugin hook API and forwards it to an agentmemory API server. It records prompts, tool activity, compaction events, permission prompts, and session lifecycle signals, then injects recalled memory context into future system and compaction prompts.

Features

• Captures prompts, tool inputs/results, tool failures, compaction events, permission prompts, and lifecycle events.
• Starts and ends agentmemory sessions from Kilo/OpenCode session events.
• Injects recalled session context into the system prompt by default.
• Adds recalled context to compaction prompts.
• Supports optional pre-tool enrichment for file/search tools.
• Supports optional stop summarization, consolidation, and Claude memory bridge sync endpoints.
• Redacts common secret formats before sending data to agentmemory.
• Treats agentmemory calls as best-effort so hook failures do not break Kilo/OpenCode execution.

Requirements

• Node.js 18 or newer.
• Kilo or OpenCode with @opencode-ai/plugin-compatible plugin support.
• A running agentmemory API server.

Start agentmemory locally:

npx @agentmemory/agentmemory

By default, agentmemory serves the API at http://localhost:3111 and the viewer at http://localhost:3113.

Quick Start

Build the plugin:

npm install
npm run build

Add the compiled plugin to your Kilo or OpenCode config:

{
  "plugin": [
    [
      "file:///absolute/path/to/kilo-agentmemory-bridge/dist/server.js",
      {
        "url": "http://localhost:3111",
        "tokenBudget": 2000
      }
    ]
  ]
}

If your agentmemory server requires bearer authentication, add secret:

{
  "plugin": [
    [
      "file:///absolute/path/to/kilo-agentmemory-bridge/dist/server.js",
      {
        "url": "http://localhost:3111",
        "secret": "replace-with-bearer-token"
      }
    ]
  ]
}

For project-local Kilo config, keep secrets in .kilo/kilo.json and keep that file out of git.

How It Works

Kilo/OpenCode loads dist/server.js as an OpenCode plugin module. The plugin exports a PluginModule whose server(input, options) function returns hook handlers such as chat.message, tool.execute.before, tool.execute.after, permission.ask, experimental.chat.system.transform, and experimental.session.compacting.

Those hooks translate Kilo/OpenCode runtime activity into agentmemory API calls:

The agentmemory MCP server is complementary. Use MCP for interactive memory tools; use this plugin for passive hook capture and automatic context injection.

Configuration

Plugin tuple options override environment variables, which override defaults.

Equivalent environment configuration:

export AGENTMEMORY_URL=http://localhost:3111
export AGENTMEMORY_TOKEN_BUDGET=2000
export AGENTMEMORY_SECRET=replace-with-bearer-token

Session context injection is enabled by default for this bridge. Disable it with injectSessionContext: false or AGENTMEMORY_INJECT_SESSION_CONTEXT=false.

Hook Coverage

agentmemory already defines a Claude Code hook vocabulary. This bridge maps that vocabulary onto the closest Kilo/OpenCode plugin hooks and runtime events.

Pre-tool enrichment is stored for the next safe system-prompt transform. Kilo/OpenCode does not currently expose the same pre-tool stdout injection channel used by Claude Code hooks.

Session Lifecycle

session.idle is treated as a stop/turn-idle signal. The bridge records a throttled stop observation and, by default, requests agentmemory summarization.

session.deleted is treated as terminal session end. Terminal cleanup can also run optional consolidation and bridge sync endpoints when enabled.

Privacy

Prompt and tool data is redacted before being sent to agentmemory.

The redactor handles:

• <private>...</private> blocks
• Bearer tokens
• OpenAI-style sk-* keys
• GitHub ghp_, gho_, ghu_, ghs_, ghr_, and github_pat_ tokens
• AWS access key IDs
• JWT-looking strings
• Object values whose keys look like keys, secrets, passwords, tokens, auth, or credentials

Tool output is truncated to 8000 characters. Image-like data URLs, PNG base64 payloads, and JPEG base64 payloads up to 1,000,000 characters are extracted into image_data; larger image payloads are omitted.

Redaction is best-effort and should not be treated as a security boundary.

Validation

Run local checks:

npm run typecheck
npm run build

Validate Kilo config loading:

kilo config check --print-logs --log-level DEBUG

Use kilo config check for validation when local config contains bearer tokens. kilo debug config may print resolved secret values.

Publishing

This package is configured for tag-based releases and npm trusted publishing from GitHub Actions.

Pushing a new vX.Y.Z tag runs two workflows:

• .github/workflows/create-release.yml creates a GitHub Release with generated release notes.
• .github/workflows/publish-npm.yml publishes the same version to npm with trusted publishing.

Before the workflow can publish with OIDC, configure npm trusted publishing for this package on npmjs.com:

• Publisher: GitHub Actions
• Repository: piotrpaj/kilo-agentmemory-bridge
• Workflow file: publish-npm.yml
• Environment: leave blank unless the workflow is updated to use a GitHub environment

Trusted publishing requires npm CLI 11.5.1 or newer and Node.js 22.14.0 or newer. The workflow uses Node.js 24.x so the bundled npm supports OIDC publishing and automatic provenance.

For a release publish, update package.json and package-lock.json to the target version, commit the change, tag the same commit as vX.Y.Z, and push the tag. Both workflows verify that the tag matches package.json before publishing or creating the release.

If npm does not allow trusted publisher setup before the package exists, do one initial manual publish from a clean checkout with an npm account that can publish the package: npm publish --access public --provenance=false. After that, configure trusted publishing and use vX.Y.Z tag pushes for future releases.

Troubleshooting

License

MIT