Integrations

Connect Borg to MCP-capable clients, configure client instructions, and keep memory behavior consistent across tools.

MCP, AGENTS.md, steering files, hooks, and REST ingestion.

How Borg Integrates

One MCP endpoint, four tools, and a small amount of client-specific setup.

Borg exposes a Streamable HTTP MCP server at /mcp. The surface is intentionally narrow: borg_think for context compilation, borg_learn for capture, borg_recallfor direct lookup, and borg_get_episode for opening a full stored episode after recall. The OSS release runs locally with no authentication required.

borg_think

Compile context before complex work.

borg_learn

Record decisions and discoveries for later reuse.

borg_recall

Search raw memory when you want direct evidence.

borg_get_episode

Fetch one full episode by ID after browsing previews.

Generic Use Cases

Engineering

Ask Borg what changed, how a bug was fixed, or which assumptions still hold before editing a risky path.

Operations

Capture incident notes, runbooks, release decisions, and environment policies so the next operator starts with context.

Product and Support

Recall feature requests, customer commitments, positioning notes, and prior decisions without repeating the same history.

Zero-SDK Ingestion

Install once, then borg init adds memory to any project without touching your code.

Borg ships a CLI installer. Run the one-liner to install, then run borg init in any project directory. The init command writes the MCP configuration and generates agent-hook templates for every supported client: CLAUDE.md, AGENTS.md,kiro.md, and copilot-instructions.md. No SDK imports, no code changes, no new dependencies in your project. The next Claude Code, Codex, Kiro, or Copilot session in that directory will have Borg available automatically.

Install and initialize
# Install the Borg CLI
curl -fsSL https://raw.githubusercontent.com/villanub/borgmemory/main/install.sh | sh

# Initialize Borg in your project
cd your-project
borg init

# Optional: cold-start from existing docs
borg bootstrap --dir ./docs --namespace my-project

What borg init does

MCP configuration

Writes or updates the client-specific MCP config so Claude Code, Codex, and Kiro can connect to Borg immediately.

Agent-hook templates

Generates CLAUDE.md, AGENTS.md, kiro.md, and copilot-instructions.md with Borg usage instructions so every AI client knows when to call borg_think and borg_learn.

Namespace detection

Derives a project namespace from the directory name or git remote so memory stays isolated per project from the first session.

Client Setup

Use the client-native MCP configuration where possible. borg init handles this automatically — manual steps are here for reference.

Claude Code

{
  "mcpServers": {
    "borg": {
      "command": "bash",
      "args": [
        "-lc",
        "export MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/claude-borg && exec npx -y mcp-remote@0.1.28 http://localhost:8080/mcp 35535"
      ]
    }
  }
}

Claude Code works with Borg through mcp-remote@0.1.28, which handles FastMCP 3 OAuth discovery and the browser sign-in flow. Keep your project instructions in CLAUDE.md.

Codex CLI

# ~/.codex/config.toml
mcp_oauth_credentials_store = "keyring"

[mcp_servers.borg]
command = "bash"
startup_timeout_sec = 30
args = [
  "-lc",
  "export MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/codex-borg && exec npx -y mcp-remote http://localhost:8080/mcp 35534 --resource http://localhost:8080/mcp",
]

Codex CLI works cleanly through mcp-remote with its own auth cache directory and callback port. Start a fresh Codex session after adding the config and Codex will launch the Borg MCP process and complete the browser sign-in flow automatically.

Kiro CLI

// ~/.kiro/settings/mcp.json
{
  "mcpServers": {
    "borg": {
      "command": "bash",
      "args": [
        "-lc",
        "export MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/kiro-borg && exec npx -y mcp-remote@0.1.28 http://localhost:8080/mcp 35536"
      ],
      "autoApprove": [
        "borg_think",
        "borg_learn",
        "borg_recall",
        "borg_get_episode"
      ]
    }
  }
}

Kiro supports global and local MCP settings, per-agent mcpServers, plus steering files and richer hooks. The verified setup uses mcp-remote@0.1.28 directly so Kiro can complete Borg's OAuth flow in the browser.

GitHub Copilot

// .vscode/mcp.json
{
  "servers": {
    "borg": {
      "command": "bash",
      "args": [
        "-lc",
        "export MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/copilot-borg && exec npx -y mcp-remote@0.1.28 http://localhost:8080/mcp 35537"
      ]
    }
  }
}

Copilot reads MCP server config from .vscode/mcp.json. Keep project instructions in copilot-instructions.md (generated by borg init).

Instructions and Steering

Tell each client when Borg should be consulted and when new knowledge should be captured.

ToolGlobal instructionsProject instructionsHooks
Claude Code~/.claude/CLAUDE.mdCLAUDE.mdPostSession
Codex CLI~/.codex/AGENTS.mdAGENTS.mdNone native
Kiro CLI~/.kiro/steering/AGENTS.mdAGENTS.md or .kiro/steering/*.mdstop, postToolUse, agentSpawn
GitHub CopilotN/Acopilot-instructions.mdNone native
Claude DesktopProject system prompt (UI)Project system prompt (UI)None

Global guidance

## Borg Memory System
Call borg_think before complex tasks to retrieve professional context.
Call borg_learn after significant decisions or discoveries.
Call borg_recall when you want raw memory or direct evidence.
Use namespace "plurality" for Multi-Tool work coordination, "borg" for Borg dev, "default" for general.

Put the same block in each client's global instruction file so Borg is available even outside a project folder.

Borg repo override

## Borg Namespace

For this repository, use Borg namespace "borg".

Always pass namespace="borg" to:
- borg_think
- borg_learn
- borg_recall

Do not omit the namespace.
Do not use "default" for work in this repository.

Use a project instruction file to pin the exact namespace for one repository. In this repo, add this block to CLAUDE.md or AGENTS.md.

Kiro steering

# Global
~/.kiro/steering/AGENTS.md
~/.kiro/steering/*.md

# Per-project
AGENTS.md
.kiro/steering/*.md

Use AGENTS.md for cross-tool behavior and Kiro steering files when you want Kiro-specific guidance.

Claude Desktop project instructions

# Project Settings → Instructions
## Borg Memory System
Call borg_think before complex tasks to retrieve professional context.
Call borg_learn after significant decisions or discoveries.
Call borg_recall when you want raw memory or direct evidence.

When to call borg_think:
- Starting work on any topic you haven't seen context for
- Debugging, architecture, compliance, or writing tasks
- When asked about prior decisions or project history

When to call borg_learn:
- A significant decision is made
- A bug is diagnosed and fixed
- A new pattern or convention is established
- Important context that should persist across sessions

Always use namespace "plurality" for Multi-Tool work coordination,
"borg" for Borg development, "default" for general knowledge.

Manual ingestion

1. Open /docs
2. Click Authorize and complete Entra sign-in
3. Run POST /api/learn with:

{
  "content": "Decided to add a release-readiness checklist before production deploys...",
  "source": "manual",
  "namespace": "product-engineering"
}

REST remains useful for scripts, manual capture, and recovery workflows. Use the live docs OAuth flow instead of pasting tokens into client config. This assumes backend docs are enabled with BORG_ENABLE_DOCS=true.

Operational Notes

A few integration details matter in practice.

Authentication

The OSS release runs locally with no authentication — all requests pass through to the local Borg process. The mcp-remotewrappers shown above forward MCP traffic from each client to the local server; give each client its own callback port and auth cache directory so sessions don't collide.

Graceful degradation

If Azure OpenAI extraction settings are missing, Borg can still ingest episodes and keep them searchable by recency. When extraction becomes available again, failed items can be requeued through the admin API.

Open Live API Docs