Connect to Claude
Choose the method that fits how you use Claude. All three connect to the same Backpack platform.
Claude App & Cowork (no terminal)
- Open Claude settings → Integrations → Add custom connector
- Enter the server URL:
https://app.backpackontology.com/mcp/sse
- Enter the OAuth Client ID:
2d84f4b4-0c8c-4eb5-8f26-4dabc7f07551
- Leave Client Secret blank → click Add → sign in when prompted
Claude Code (terminal, cloud)
claude mcp add backpack-app -s user --transport sse https://app.backpackontology.com/mcp/sse
A browser window opens for sign-in on first run. After that, it's automatic. Restart Claude Code to activate.
Claude Code (terminal, local)
claude mcp add backpack-local -s user -- npx backpack-ontology@latest
Everything stays on your machine. No account needed. Restart Claude Code to activate.
Your first learning graph
Just talk naturally. Claude handles the structure automatically.
Tell Claude what to remember
"Remember that Acme Corp is on the Enterprise tier, main contact is Sarah Chen"
"Start a learning graph for our hiring process"
"Add the new vendor agreement details to backpack"
Claude creates a learning graph and populates it with nodes (things) connected by edges (relationships). Types and properties are freeform — Claude picks whatever structure fits the domain.
Find something later
"What's in my backpack about Acme Corp?"
"Search backpack for anything related to compliance"
Claude searches across all properties in your learning graphs and pulls in only what's relevant — keeping the context window lean.
See the big picture
"Show me my learning graph"
"Give me a link to the graph"
Claude responds with a clickable link to the graph visualizer, focused on the nodes you're discussing.
Local vs Cloud
| Local | Cloud |
|---|
| Storage | JSON files at ~/.local/share/backpack/ontologies/ | Hosted at app.backpackontology.com |
| Access | This machine only | Any device, any browser |
| Visualizer | npx backpack-viewer (localhost) | Built into the web app |
| Account | Not needed | Free sign-up |
| Sharing | Share via viewer (syncs to cloud) | Encrypted share links, free tier included |
You can start local and move to cloud anytime. Both use the same MCP tools and data format.
Syncing to Cloud
If you've been using Backpack Local and want to move to the cloud, tell Claude:
"Sync my backpack to the cloud"
This uploads all your local learning graphs to Backpack App. Then update your MCP config to use the cloud connection:
claude mcp add backpack-app -s user --transport sse https://app.backpackontology.com/mcp/sse
Sharing
The share button in the viewer syncs your graph to your cloud backpack and generates a share link with access controls.
How it works
- Click Share in the viewer toolbar
- Sign in with your Backpack account (OAuth, one-time prompt)
- Your graph syncs to your cloud backpack
- You get a share link you can send to anyone
The first sync creates the cloud copy and share link. Re-syncing updates the cloud copy and preserves existing links, so anyone with the link always sees the latest version.
Access control
Links can be revoked, expired, or scoped to specific recipients from your Backpack App settings. You stay in control of who sees what.
Free tier
| Quota | Limit |
|---|
| Private graphs | 1 |
| Public graphs | 4 |
| Share link expiry | 7 days |
When you reach the private graph quota, you can choose to publish to the graph commons instead. This requires explicit confirmation, so nothing goes public silently.
Opening a shared graph
Recipients open the link in any browser. No install needed. The graph loads in the viewer with whatever access scope you set.
Graph visualizer
Backpack includes a web-based graph visualizer with force-directed layout, type clustering, and live reload.
Nodes are colored by type and clustered together automatically. Edges show relationship types between nodes. Pan by dragging, zoom with scroll wheel.
Changes made via Claude appear in the visualizer in real time — no refresh needed.
Minimap
A small overview in the bottom-right corner shows the entire graph and your current viewport. Useful for orientation in large graphs.
Type regions
Dashed ellipses group nodes of the same type together visually. Toggle on/off from the graph inspector.
Graph inspector
Click the menu icon in the top-left corner of the canvas to open the graph inspector panel. It shows:
- Stats — total nodes, edges, and type count at a glance
- Node types — click to filter the canvas, click the pencil to bulk rename all nodes of that type
- Edge types — with counts and bulk rename
- Most connected — the hub nodes with the most relationships. Click to navigate.
- Quality — orphan nodes (no connections) and singleton types (possible typos)
- Controls — toggle edge labels, type regions, minimap. Adjust clustering strength and spacing with sliders.
- Export — download the current view as PNG or SVG with a
backpackontology.com watermark
Editing
Click any node in the canvas to open the info panel on the right. From there you can:
- Edit property values inline (text fields auto-expand for long content)
- Add new properties with the + button
- Change the node type
- Delete nodes and edges
- Navigate to connected nodes by clicking relationship links
- Expand the panel to full screen for complex nodes
All changes save automatically and update the canvas in real time.
Use Ctrl+Z to undo and Ctrl+Shift+Z to redo (up to 30 steps per session).
Export
Open the graph inspector and scroll to the Controls section. Two export options:
- Export PNG — raster image of the current canvas view, scaled for clarity
- Export SVG — vector image, ideal for presentations and documents
Both include a subtle backpackontology.com watermark in the bottom-right corner.
Keyboard shortcuts
Press ? in the viewer to see this overlay.
| Key | Action |
|---|
| / or Ctrl+K | Focus search |
| Ctrl+Z | Undo |
| Ctrl+Shift+Z | Redo |
| ? | Show shortcuts help |
| Esc | Close panel / clear search |
| Click | Select node |
| Ctrl+Click | Multi-select nodes |
| Drag | Pan canvas |
| Scroll | Zoom in/out |
Auto-capture
Backpack installs lightweight hooks that review your Claude conversations after each session. If meaningful knowledge was discussed — client details, architecture decisions, process changes — Claude saves it to the appropriate learning graph automatically.
Auto-capture is selective: it skips debugging sessions, casual conversation, and trivial Q&A. Only knowledge with lasting value gets captured.
To disable: remove the backpack hooks from .claude/settings.json. To re-enable: npx -p backpack-ontology@latest backpack-init
Term Registry
When Claude adds nodes to a learning graph, the MCP server provides a list of existing node types, edge types, and entity names. This nudges Claude to reuse consistent terms instead of creating duplicates like "Service" and "Microservice" or "AuthService" and "auth-service".
The Term Registry is generated automatically from your graph data — no configuration needed. It improves with every extraction as the graph grows.
You can see the registered types in the graph inspector panel. Use the pencil icon to bulk rename a type across all nodes.
Deep links
Every node has a shareable URL. When Claude searches your graph or returns node details, it includes a clickable link that opens the visualizer focused on those specific nodes.
URL format
| Context | Format |
|---|
| Local viewer | http://localhost:5173#graph-name?node=id1,id2 |
| Cloud app | https://app.backpackontology.com/graph/{uuid}?node=id1,id2 |
Clicking a node in the viewer updates the URL automatically. Copy it to share a focused view with a teammate.
MCP tools
Claude uses these automatically. You don't need to call them directly.
| Action | Tool |
|---|
| List learning graphs | backpack_list |
| Inspect graph structure | backpack_describe |
| Create a new graph | backpack_create |
| Search across properties | backpack_search |
| Browse nodes by type | backpack_list_nodes, backpack_node_types |
| Get full node details | backpack_get_node |
| Explore connections | backpack_get_neighbors |
| Add a node | backpack_add_node |
| Update a node | backpack_update_node |
| Add a relationship | backpack_add_edge |
| Bulk import | backpack_import_nodes |
| Remove a node | backpack_remove_node |
| Remove a relationship | backpack_remove_edge |
| Delete a graph | backpack_delete |
| Rename a graph | backpack_rename |
CLI commands
The Backpack package ships several entry points. The first four are single-purpose; bp is the full-featured CLI — see bp CLI below.
| Command | What it does |
|---|
bp | The standalone bp CLI (read on) |
npx backpack-ontology@latest | Start the local MCP server |
npx backpack-viewer | Open the graph visualizer at localhost:5173 |
npx -p backpack-ontology@latest backpack-sync | Upload local learning graphs to Backpack App |
npx -p backpack-ontology@latest backpack-init | Reinstall auto-capture hooks |
bp CLI
A scriptable command-line interface for Backpack. Query your knowledge graph from the terminal, pipe data into jq, or wire Backpack into shell scripts.
Install
npm install -g backpack-ontology
Run bp with no arguments for a hint card. bp help shows the full reference.
Tab completion
bp completion zsh > "${fpath[1]}/_bp"
Bash and fish are also supported: bp completion bash, bp completion fish.
Daily-driver verbs
| Command | What it does |
|---|
bp ls | list graphs in the current scope |
bp ls containers / bp ls kbs | list cloud containers / KB documents |
bp cat <name> | print a graph as JSON to stdout (pipeable to jq) |
bp show <name> | human-friendly summary + type histogram |
bp open <name> | launch the viewer focused on this graph |
bp search <query> | full-text search across visible graphs |
bp rm <name> | delete a graph (asks for confirmation) |
bp mv <old> <new> | rename a graph |
bp where | show the current scope (backpack / container / identity) |
bp use <name> | switch context (fuzzy-matched, with did-you-mean on typos) |
bp doctor | auth, connectivity, version skew checks |
Auth
| Command | What it does |
|---|
bp login | OAuth flow against Backpack App. Token is shared with the viewer's Sign In. |
bp logout | clear every known token location (loud on partial failure) |
bp whoami | show signed-in identity + endpoint |
Graph mutations
| Command | What it does |
|---|
bp graphs create <name> [--description=…] | new empty graph |
bp graphs create <name> --from-file <f> | create from a JSON file |
bp graphs apply -f <file> | upsert from a JSON file (atomic; preserves snapshots, branches, snippets) |
bp graphs edit <name> | open in $EDITOR; structural-no-op detection |
bp graphs rename <old> <new> | rename in place |
bp graphs delete <name> [-y] | delete with confirmation |
bp graphs move <name> --to <container> | relocate a cloud graph between containers |
Knowledge-base documents
| Command | What it does |
|---|
bp kbs list | list KB docs in the current scope |
bp kbs get <id> | print body to stdout |
bp kbs create -f <file.md> | create from a markdown file (auto-strips leading frontmatter) |
bp kbs create --title=… --content=… | create from flags |
bp kbs edit <id> | edit body in $EDITOR |
bp kbs delete <id> | delete with confirmation |
bp kbs move <id> --to <container> | relocate between cloud containers |
Cloud admin (Backpack App)
| Command | What it does |
|---|
bp containers list | list your cloud sync_backpacks |
bp containers create <name> [--color=#xxx] [--tags=a,b] | new cloud container |
bp containers rename <old> <new> | rename / recolor / retag |
bp containers delete <name> | delete (refuses if non-empty — move artifacts out first) |
Output formats
| Flag | Output | Stable contract? |
|---|
| (default) | human-friendly table with colors, narrows on small terminals | no — free to evolve |
--json | full JSON | yes — script against this |
--yaml | YAML | yes |
--names | one name per line | yes |
--wide | every column (still human) | no |
--no-color | strip ANSI codes (also honors NO_COLOR=1) | n/a |
Scripts should pipe --json through jq or use --names. The default human view is allowed to change between releases.
Exit codes
| Code | Meaning |
|---|
| 0 | success |
| 1 | failure (any kind — auth, validation, network, server error) |
| 130 | user-interrupted ($EDITOR session aborted with Ctrl-C) |
Destructive verbs (rm, mv, containers delete, kbs delete) prompt for confirmation in a TTY and refuse in non-TTY contexts unless you pass -y / --yes.
Examples
Common one-liners:
bp ls --json | jq '.graphs[] | {name, nodeCount}'
bp cat agent-capability-iac | jq '.nodes | group_by(.type) | map({type: .[0].type, count: length})'
bp graphs apply -f exported.json
for g in $(bp ls --names); do bp show $g; done
Configuration
| Environment variable | Effect |
|---|
XDG_DATA_HOME | Override local data directory (default: ~/.local/share) |
XDG_CONFIG_HOME | Override config directory (default: ~/.config) |
BACKPACK_DIR | Override all Backpack directories |
DO_NOT_TRACK | Disable anonymous telemetry |
BACKPACK_TELEMETRY_DISABLED | Disable telemetry (alternative) |
BACKPACK_TELEMETRY_URL | Override telemetry endpoint (dev use) |
You can also set {"telemetry": false} in ~/.config/backpack/config.json.
Privacy & telemetry
The open source MCP server collects one anonymous summary event per session: tool call counts, session duration, and aggregate graph stats (how many nodes and edges). No content, names, property values, or personal data is ever collected.
Opt out with any of:
export DO_NOT_TRACK=1export BACKPACK_TELEMETRY_DISABLED=1- Add
{"telemetry": false} to ~/.config/backpack/config.json
Full policy: Backpack Local Privacy Policy · Backpack App Privacy Policy