Firekeep documentation

Architecture

Firekeep is two halves. A server you run once, and a client kit installed on each developer machine that wires your agent runtimes into it.

Server services

Backed by three datastores in the same stack—Neo4j (knowledge graph), Qdrant (vector embeddings) and Redis (cache, queues, streams)— plus Ollama for local model inference.

Client kit

Installs to ~/.firekeep and renders configuration for whichever agent runtimes you use — Claude Code, Codex, Kiro and OpenCode are configured together. It provides the MCP gateway your agent talks to, plus lifecycle automation where each runtime's hook surface allows it. The day-to-day section below names the current differences explicitly.

Symdex code intelligence runs client-side. It has to be local to the code it indexes, so it ships as a stdio MCP server on your machine rather than in the server stack. The Decision Board is client-side too: it opens an ephemeral loopback browser surface and returns submitted answers to the waiting agent.

Capability map

Firekeep joins durable memory, working context, code intelligence and agent coordination. The boundaries below are part of the product: it records what agents explicitly send and automates only the lifecycle events each client exposes.

Symdex local code intelligence

Symdex is installed and registered automatically with Firekeep. It parses your working tree locally with tree-sitter and gives supported agents focused codebase context through MCP.

The built-in parsers cover Python, JavaScript, TypeScript, Go, Rust, Java, PHP, C, C#, Ruby, Kotlin and Swift. Depending on the language's syntax, the index captures functions, classes, methods, types, constants, routes and their relationships. Thirty tools are available by default for symbol lookup, search, callers, architecture, impact and related context; eight heavier analytics tools are optional.

Symdex can serve symbol-level context when that is sufficient and include broader file context when an edit needs it. Firekeep's code-and-memory tools can also cross-reference the current code with decisions, fixes and change history recalled from earlier sessions.

Targeted symbol benchmark

The repeatable benchmark compares the stable response from a verified Symdex symbol lookup with reading that symbol's entire containing file. It uses one pinned public repository per supported language and 30 deterministic, file-balanced functions, methods, classes or types from each repository. Test, fixture, example and benchmark paths are excluded. No generation model or subjective judge is involved.

The primary result is the mean of all 360 per-lookup reductions, with equal samples per language and file-balanced selection within each project. Token counts use the cl100k_base encoding; o200k_base produces a similar 54.54% result. Every indexed file and returned source was also checked byte-for-byte against its pinned Git blob. That exact-source check shows the requested code was preserved; it is not an answer-accuracy score. Results varied substantially: the median reduction was 78.42%, while 58 of 360 lookups used more tokens because the serialized tool response can exceed an already small source file. The benchmark measures direct known-symbol retrieval versus a whole-file baseline—not symbol discovery, ordinary range reads, complete agent tasks or whole-session use.

Mixed-task Click benchmark

A separate archived benchmark asked 20 comprehension, navigation and modification questions about Click, with three generated answers per question and an LLM judge. Across the 20 unique context comparisons, Symdex consumed 23.31% fewer total context tokens. Its judged-accuracy point estimate was 4.42 versus 4.45 for raw-file context.

This older result is an in-sample observation, not proof of equal answer quality or a guarantee for other repositories. The accuracy difference was small, but the sample was not designed to establish statistical non-inferiority. Modification questions consumed more context because the tested builder combined raw files with structural analysis.

Working-state restore benchmark

When an agent's context window is compacted, it restores its working state from the session server. That restore returns the whole session document — plan, decisions, file knowledge, progress and scratchpad — and still does by default. An agent may instead hand back an opaque cursor and receive only what changed since it last looked. This benchmark measures the difference between those two responses. No generation model or subjective judge is involved; token counts use the cl100k_base encoding.

This is a per-restore reduction, not a per-request one. A delta is only returned when an agent asks to restore its working state, which happens after a context compaction rather than on every turn. Read that before comparing this figure with any per-request cost.

The spread is wide and the mean hides it: per-session reductions ranged from 0.8% to 67.4%. The weak cases are structural rather than noise. Scratchpad entries are stored without per-entry timestamps, so a delta has nothing to filter on and always returns them in full; the same applies to proactively recalled memories, which are replaced wholesale rather than appended. Scratchpad alone accounted for 14.1% of all measured session tokens. Of the reduction that does occur, 80% comes from filtering decision, progress and file entries and only 20% from omitting an unchanged plan.

These 26 sessions came from a single operator on a single machine, so the result is an in-sample observation rather than a prediction for another team's usage pattern. A separate check against a live deployment on 2026-08-01 reduced one session's restore from 12,122 to 4,977 characters — a character-level measurement of one session, reported here because it is a production observation rather than a simulation, not because one session establishes a rate.

The delta is opt-in. An agent that never sends a cursor receives byte-identical output to before, and six independent conditions — an absent, unparsable, wrong-session, stale, unreadable or unanchored cursor — each return the complete document rather than a partial one. Where the mechanism can be wrong, it returns too much rather than too little. A restore that omits content states what it withheld and how to retrieve it, so an agent reading a delta cannot mistake an omission for an absence.

Requirements

Server

• Linux host with Docker and Docker Compose v2
• Git
• 16 GB RAM recommended for the default stack
• No open ports required — a default install binds to 127.0.0.1

Client

• macOS, Linux or Windows
• Nothing preinstalled — the bootstrap fetches its own pinned toolchain
• Installing from a source checkout instead needs a system python3 >= 3.10

Solo and Team

Firekeep has one client, one server and one capability set. The commercial boundary is people—not agents, devices or individual features.

Server installation

The public path provisions the same self-hosted server for Solo and Team. It does not ask you to choose a plan and does not require a registry account or license token.

1. Install the Firekeep client kit on the Linux Docker host
   on the serverCopy

   $ curl -fsSL https://kapella-hub.github.io/firekeep-dist/latest/install.sh | sh

   The bootstrap brings its own pinned Python toolchain and verifies downloads before use.

2. Provision the latest public server release
   on the serverCopy

   $ firekeep init

   It downloads and checksum-verifies a source-free deployment bundle, then pulls the public Firekeep images.

3. Add your workstation

   On a remote server, first install the client kit on your workstation, then run firekeep connect user@server --remote-dir ~/.firekeep/server. The explicit directory matches the public install default. The command uses your existing SSH access to issue a single-use code, enroll this first device and open a reusable local tunnel. Visit http://127.0.0.1:8040/, enter the admin key printed by init, and use Dashboard → Devices → Add device for later workstations. Dashboard-issued join codes are single-use and valid for 24 hours.

Only the four Firekeep service images are published. Neo4j, Redis, Qdrant and Ollama are pulled by your own Docker daemon from their upstream registries — Firekeep never redistributes them.

As a developer — build from source

From a checkout of the repository you have been granted access to:

A source checkout builds the Firekeep services locally. Add --pull only when deliberately testing the published-image path.

What the installer does

• Checks for Docker and Compose v2, installing Docker if absent
• Prompts for host address and Neo4j password, writing a validated .env at mode 600
• Generates a vault encryption key
• Mints API keys and prints an admin key exactly once
• Pulls public images or builds source images, then starts the complete stack

Your first authenticated call

A fresh install is closed by default in two independent ways.

Both are deliberate. A stock install used to publish six ports on every interface and treat every caller as an anonymous admin — enough to read the vault and mint keys.

Server configuration

Everything lives in .env beside the compose file. The settings that actually change behaviour:

Client installation

One command on a bare machine. No system Python or Node required.

What the bootstrap does

1. Resolves the version and fetches that version's checksum manifest once.
2. Verifies before use. Both a mirrored toolchain and the client wheel are checksum-verified against that manifest before either is executed. The wheel is fetched to a local file and installed by path — never by URL, which does no hash checking, and never by name.
3. Installs the kit into ~/.firekeep with its own standalone Python.
4. Renders every shipped adapter for Claude Code, Codex, Kiro and OpenCode.

Recommended device enrollment

On an existing server, open Dashboard → Devices → Add device and run the generated command. It supplies a single-use join code, so there are no profile, host, API-key, plan or runtime prompts. The client creates its credential locally, redeems the code once, writes the single server connection and runs firekeep doctor. Device credentials default to 90 days; doctor warns during the final 14 days, and a new join code rotates the device onto a fresh credential.

From a source checkout

./install installs the kit and renders adapters. firekeep install run from that environment re-renders adapters only — it skips the package install, because the code it would install is the code already running.

Use firekeep install --runtime <name> only to repair or re-render one adapter. A normal install prepares all four supported clients together.

Connecting a device

A dashboard join code is the normal attachment path. The code identifies the server and enrollment ticket; the client chooses its own credential and stores one connection.

SSH shortcut for operators

An operator who already has shell access can use firekeep connect. It issues a single-use code over SSH and then calls the same join path locally:

Restart your agent session afterwards so it picks up the newly registered MCP servers.

CLI reference

Start with doctor

When anything is wrong, this is the first command to run — it checks the whole chain rather than one link.

Day to day

The core MCP capabilities work through every shipped adapter. Lifecycle automation varies because each coding client exposes different hook surfaces.

Automation by client

These differences affect convenience, not access to the underlying MCP capabilities. Every supported client can call the same server tools when its agent chooses to do so.

What your agent calls directly

Firekeep exposes its server capabilities through one local gateway, with Symdex and Decision Board running client-side. The tools that matter in ordinary work include:

The dashboard

Served on port 8040. Because the stack binds to loopback, reach it through the tunnel connect established — at http://127.0.0.1:8040/, not the server's own address.

Personal mode

An escape hatch that makes Firekeep dormant for work you do not want it to record.

Hooks, the presence sidecar and Decision Board re-read the state and stop communicating immediately. An MCP shim that is already running evaluates hard bypass only when it starts, so restart the active agent after changing Personal mode. A restarted shim exposes zero Firekeep tools while the mode is on; restart again after turning it off to restore them.

Operations

Updating

What version am I running?

Every service answers /version without a key and without touching its dependencies, so it responds even when the things behind it are down.

Health

Backups

Use the shipped deploy/backup.sh so Neo4j, Qdrant and Redis are quiesced before their files are copied. It archives the four base volumes together: Neo4j, Qdrant, Redis and Ollama. A partial or hot filesystem copy can look valid while containing inconsistent graph, vector or auth state.

Troubleshooting

Everything returns 401

Expected on a fresh install — AUTH_ENABLED=true is the default. Confirm the service is actually up with the keyless /health, then check that your client connection has an API key. firekeep doctor reports a missing or rejected key directly.

Connection refused from another machine

Also expected. BIND_ADDR=127.0.0.1 means the ports answer only on the host. Use the connection encoded by the dashboard join code, establish an SSH/private-network route, or run the operator shortcut firekeep connect user@host --remote-dir ~/.firekeep/server. Pointing a client at an unbound public address simply times out.

The dashboard says a service is unreachable

Check the service directly on the host with curl against /health. If that answers and the dashboard disagrees, the proxy in front of the dashboard is misrouting rather than the service being down.

Containers restart or get killed

Almost always memory. Check docker stats against the requirements above. The symptom is misleading: health checks keep passing while the process inside is killed and restarted.

The agent does not see the tools

MCP servers are registered at install, and a running agent session does not pick up new ones. Restart the session. If they are still missing, firekeep install --runtime <name> re-renders that runtime's configuration.

Still stuck

Run firekeep doctor and include its output when you get in touch. It reports the whole chain — connection, auth, versions, permissions — rather than one link of it.