backpack-connector

Graph database projection connectors for Backpack learning graphs.

Projects Backpack event logs into graph databases for Cypher traversals, vector search, and graph analytics. Includes a unified MCP server that combines all backpack-ontology tools with connector query tools — one server, one config entry in Claude.

Supported adapters

| Adapter | Languages | Status | |---|---|---| | arcadedb | Cypher (OpenCypher), SQL, Gremlin | stable |

Installation

npm install -g backpack-connector

Requires Node.js >= 18 and a running ArcadeDB instance. See ArcadeDB quickstart below.

Quick start

# 1. Project a graph into ArcadeDB
backpack-connector project --graph my-graph

# 2. Query it
backpack-connector query --graph my-graph \
  --cypher "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 10"

# 3. Wire Claude to use the unified MCP server
backpack-connector mcp-config
# Copy the output into ~/.claude/settings.json

Commands

project

Project a Backpack learning graph into ArcadeDB. Incremental — only processes new events since the last run.

backpack-connector project \
  --graph <name>              # required: graph name
  [--backpack-path <path>]    # defaults to active backpack
  [--branch <branch>]         # default: main
  [--adapter arcadedb]        # default: arcadedb, or BACKPACK_ADAPTER env var
  [--reset]                   # clear this graph's nodes and re-project from scratch

All graphs from all backpacks land in a single ArcadeDB database named "backpack". Every node is tagged bk_backpack (which backpack it came from) and bk_graph (which learning graph). This is what makes cross-graph Cypher queries possible without any per-graph database management.

Cross-graph queries — project multiple graphs, query them together:

backpack-connector project --graph project-alpha
backpack-connector project --graph project-beta
# Both land in the same "backpack" database
backpack-connector query --cypher "MATCH (n) WHERE n.bk_graph = 'project-alpha' RETURN n.name, n.bk_type LIMIT 10"
backpack-connector query --cypher "MATCH (a)-[r]->(b) WHERE a.bk_graph <> b.bk_graph RETURN a.name, type(r), b.name LIMIT 10"

query

Run a Cypher or SQL query against a projected graph.

backpack-connector query \
  --graph <name> | --database <name>   # required
  --cypher <query>                     # Cypher (OpenCypher)
  --sql <query>                        # SQL
  [--table]                            # ASCII table output (default: JSON)
  [--adapter arcadedb]

# Examples
backpack-connector query --graph my-graph \
  --cypher "MATCH (p:Platform)-[r]->(a:API) RETURN p.name, type(r), a.name"

backpack-connector query --graph my-graph \
  --sql "SELECT name, type FROM schema:types WHERE type = 'vertex'"

schema

Show vertex types, edge types, and projection state for a projected graph.

backpack-connector schema --graph <name> [--adapter arcadedb]

daemon

Watch for new events and project them continuously (polls every 1s).

backpack-connector daemon \
  --graph <name>               # comma-separated for multiple: graph-a,graph-b
  [--backpack-path <path>]
  [--adapter arcadedb]
  [--poll <ms>]                # default: 1000

mcp-config

Print the Claude MCP configuration snippet for the unified MCP server.

backpack-connector mcp-config [--name backpack] [--adapter arcadedb]

Output goes directly into ~/.claude/settings.json. This server includes all backpack-ontology tools plus the connector tools listed below.

Unified MCP server

The MCP server (backpack-connector-mcp) is the recommended way to use this package with Claude. It runs one server process that exposes all backpack-ontology tools (graph management, KB, signals, mining, sync, etc.) plus:

Graph projection:

• connector_project — project a learning graph into ArcadeDB
• connector_query — run Cypher/SQL against a projected graph
• connector_schema — inspect schema and projection state
• connector_status — check projection progress

Cross-graph synthesis:

• connector_synthesize — merge N graphs into a unified learning graph via ArcadeDB UNION
• connector_signals — detect entities appearing in multiple graphs (cross-graph duplicate report)
• connector_signal_detect — run ArcadeDB-powered signal detectors (centrality hubs, type drift, community bridges) and merge results into the Signals panel

Signals panel customization:

• connector_signals_show — read the current Signals panel widget layout
• connector_signals_add_widget — add or update a widget (Claude writes the config, panel hot-reloads in 3s)
• connector_signals_remove_widget — remove a widget by id

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "backpack": {
      "command": "npx",
      "args": ["backpack-connector-mcp"],
      "env": {
        "BACKPACK_ADAPTER": "arcadedb",
        "ARCADEDB_URL": "http://localhost:2480",
        "ARCADEDB_USERNAME": "root",
        "ARCADEDB_PASSWORD": "arcadedb"
      }
    }
  }
}

If you have a separate backpack-ontology entry in your MCP config, remove it — the connector server is a superset.

ArcadeDB quickstart

ArcadeDB requires Java 11+. Java 21 recommended.

# Download and extract
curl -L -o /tmp/arcadedb.tar.gz \
  https://github.com/ArcadeData/arcadedb/releases/download/26.4.2/arcadedb-26.4.2.tar.gz
tar -xzf /tmp/arcadedb.tar.gz -C ~/
rm /tmp/arcadedb.tar.gz

# Start (run from its own directory)
cd ~/arcadedb-26.4.2
JAVA_OPTS="-Darcadedb.server.rootPassword=<your-password>" ./bin/server.sh

# Studio UI at http://localhost:2480

Environment variables

| Variable | Default | Description | |---|---|---| | BACKPACK_ADAPTER | arcadedb | Adapter to use | | ARCADEDB_URL | http://localhost:2480 | ArcadeDB server URL | | ARCADEDB_USERNAME | root | ArcadeDB username | | ARCADEDB_PASSWORD | arcadedb | ArcadeDB password |

Programmatic use

import { project, createAdapter, registerConnectorTools } from "backpack-connector";
import { createMcpServer, loadConfig } from "backpack-ontology";

// Project a graph
const adapter = createAdapter({ adapter: "arcadedb" });
const result = await project(adapter, {
  backpackPath: "/path/to/backpack",
  graph: "my-graph",
});

// Build a unified MCP server
const config = await loadConfig();
const server = await createMcpServer({ mode: "local", dataDir: config.dataDir });
registerConnectorTools(server, adapter);
await server.connect(transport);

Knowledge Graph in the viewer

Once backpack-connector is installed alongside backpack-viewer, the viewer's sidebar gains a live Knowledge Graph section. It shows a real-time count of projected nodes and graphs and loads the unified canvas when clicked — all backpacks, all graphs, all nodes in one view.

# Install both
npm install -g backpack-connector
npx backpack-viewer   # Knowledge Graph section activates automatically

# Project graphs to populate it
backpack-connector project --graph my-graph
backpack-connector project --graph another-graph

The viewer reads ArcadeDB directly via the same environment variables (ARCADEDB_URL, ARCADEDB_USERNAME, ARCADEDB_PASSWORD). If backpack-connector is not installed, the Knowledge Graph section stays grayed out — all other viewer features work normally.

Clicking the section opens the Graph Query panel in the viewer, where you can run Cypher against the full "backpack" database and focus results back onto the canvas.

Tutorial

See docs/tutorial-knowledge-graph.md for a full walkthrough: building learning graphs through conversation, projecting into ArcadeDB, querying with Cypher, synthesizing multiple graphs, and using the viewer Query panel.

ArcadeDB

Requires ArcadeDB 26.x and Java 21+. Download from github.com/ArcadeData/arcadedb/releases.

# Start manually
cd ~/arcadedb-26.4.2
JAVA_OPTS="-Darcadedb.server.rootPassword=<password>" ./bin/server.sh

# macOS: start automatically on login
cat > ~/Library/LaunchAgents/com.arcadedb.server.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.arcadedb.server</string>
  <key>ProgramArguments</key><array>
    <string>/bin/sh</string><string>-c</string>
    <string>cd ~/arcadedb-26.4.2 && JAVA_OPTS="-Darcadedb.server.rootPassword=arcadedb" ./bin/server.sh</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>StandardOutPath</key><string>/tmp/arcadedb.log</string>
  <key>StandardErrorPath</key><string>/tmp/arcadedb.log</string>
</dict></plist>
EOF
launchctl load ~/Library/LaunchAgents/com.arcadedb.server.plist

Architecture

The event log is the source of truth. ArcadeDB is a derived projection. See docs/event-log-format.md for the full protocol spec.

Backpack learning graphs (events.jsonl)
  ↓  backpack-connector project
ArcadeDB projection (Cypher / SQL queryable)
  ↓  backpack-connector synthesize
Unified learning graph (viewable, traversable)

Adding a new graph database backend: implement ConnectorAdapter in src/adapters/<name>/, register in src/adapter-factory.ts. The CLI, daemon, and MCP server work without changes.

License

Apache 2.0