Firekeep

Persistent memory, live environment awareness, and replayable decision traces for AI coding agents — fully self-hosted.

Firekeep is a self-hosted control plane for AI coding agents. It gives Claude Code, Codex, Kiro, OpenCode, and other MCP-capable clients persistent memory, session continuity, environment awareness, agent coordination, and replayable traces. The server stack and its default inference path are local; optional connectors and Symdex AI providers contact third-party services only when you configure them.

Website · Live demo · Install guide · Case study · Concepts

The Problem

AI coding agents are powerful, but each session starts with partial amnesia. They lose context, re-read files, miss environment state, and struggle to explain why they made a decision earlier in the workflow. When something goes wrong, there is often no reliable trace to inspect. When multiple agents work in the same codebase, coordination becomes fragile.

Firekeep fixes this by giving agents durable memory, live operational awareness, and shared coordination infrastructure.

Related MCP server: obsmcp

What Firekeep Does

Why Firekeep Is Different

Firekeep is not another chatbot wrapper or prompt orchestration layer.

It is a control plane for AI coding agents — infrastructure that sits behind your existing tools and makes them better.

• Self-hosted by default. The server, datastores, embeddings, and default generation model run on your infrastructure. Third-party egress occurs only when you opt into a connector or external Symdex AI provider.

• Built for coding agents. Not general-purpose AI. Every feature is designed for the workflow of code reading, editing, testing, and deploying.

• Persistence + observability. Most agent tools focus on making the agent smarter in the moment. Firekeep focuses on what happens between sessions and after things go wrong.

• MCP-native. Four remote services and two client-local backends expose Model Context Protocol tools through one local firekeep stdio gateway. Shipped adapters configure Claude Code, Codex, Kiro, and OpenCode; other MCP clients can be configured manually.

• Agent-agnostic. Swap the agent client without rebuilding the underlying memory and coordination layer. Cursor has a documented manual MCP path; Aider does not currently have a shipped adapter.

• A2A-discoverable. Relay publishes an Agent-to-Agent agent card at /.well-known/agent.json for capability discovery. This is discovery-only, not an A2A task-execution endpoint.

Quick Start

Prerequisites

• Any Docker host — a Linux VPS, an office server, or your own desktop (Docker Desktop on macOS, or with the WSL2 backend on Windows; run the install inside WSL2 there, since the installer is a bash script). RAM: 16 GB recommended for the full default stack (Neo4j JVM + Qdrant + Redis + Ollama + 7 Python services). 8 GB is the practical floor and requires a small embedding model (EMBEDDING_MODEL=granite-embedding:30m, EMBEDDING_DIM=384). Below that, containers are OOM-killed while HTTP health checks still pass — a failure mode that is easy to misdiagnose.

• Docker and Docker Compose v2

• Git

• No public Firekeep application ports are required. A default install binds everything to 127.0.0.1; serving another machine is an explicit opt-in (see Reaching it).

Deploy

After installing the Firekeep client, provision the latest public server release:

firekeep init

firekeep init is the provisioning path. It downloads and verifies the source-free deployment bundle, pulls public server images, and prompts only for deployment values. Pin a server release with firekeep init --version vX.Y.Z. No registry account or token is needed — the release images are public.

From a source checkout, firekeep init --server-dir . keeps the developer build path. The equivalent direct commands from an unpacked bundle or checkout are:

bash install.sh --pull  # published images
bash install.sh         # build from source

Either way the installer prompts for your VPS IP and Neo4j password, brings up the full stack (13 containers: the Cortex API / MCP / worker / beat quartet, Bridge, Sentinel, Relay, the dashboard, the Neo4j / Qdrant / Redis / Ollama backends, and a one-shot Ollama model puller), mints your API keys, and prints MCP URLs when ready.

Among those keys is an admin key generated only on the first bootstrap. It appears in the bootstrap output and is repeated in the final summary so it is harder to lose; it is never written to disk. Save it in a password manager.

The install is closed by default. AUTH_ENABLED=true, so protected MCP and REST routes need an X-API-Key; health and version probes remain public. BIND_ADDR=127.0.0.1, so application ports listen on loopback only. Installs created before the 2026-07-26 security-default change may differ. If an older guide now produces 401s or connection refusals, verify the current auth and binding settings before changing them — see docs/DEPLOYMENT.md → Access and authentication.

Reaching it

From the host, http://localhost:8040. From anywhere else, tunnel:

ssh -L 8040:127.0.0.1:8040 user@vps-host      # then open http://localhost:8040

Any private network or VPN, including Tailscale or WireGuard, can provide the route instead once the application is bound or proxied onto that network; Firekeep does not require a particular network vendor. The client only needs a reachable server URL and the correct TLS/auth configuration.

To place the application ports on a LAN/private network or behind a TLS reverse proxy, set BIND_ADDR=0.0.0.0 in .env and docker compose up -d — but read the exposure warning first: Docker's published-port rules are evaluated before ufw's, so a host firewall does not contain a published port. Do not send X-API-Key over untrusted plain HTTP; use an SSH tunnel, private network, or HTTPS termination.

Connect a client

The normal onboarding path is the same for Claude Code, Codex, Kiro, and OpenCode:

1. Open the dashboard and choose Devices → Add device.

2. Copy the generated macOS/Linux or PowerShell install command to the new machine and run it. There are no profile, host, API-key, or runtime prompts.

3. Restart the agent client after installation so it loads the single firekeep MCP entry.

The command contains a single-use, 24-hour join code. The client generates its own credential locally, redeems the code once, writes the one [server] connection, installs every shipped adapter, and runs firekeep doctor. The plaintext credential is never returned by the server or printed by default.

If the kit is already installed, use the bare code shown in the dashboard:

firekeep join fk_join_...

From a server shell, deploy/firekeep-admin invite --agent laptop --json is the dashboard-independent fallback. An operator who already has SSH access can use firekeep connect root@<server>; it issues the same single-use code remotely and then calls the same join path. A working tunnel is reused, not duplicated.

The kit lives in ~/.firekeep — one venv per version under venvs/<version>, selected by the ~/.firekeep/current link that every rendered path routes through, so updates never require closing agent sessions — and prepares every shipped adapter by default: Claude Code, Codex, Kiro, and OpenCode. Claude gets user-scoped ~/.claude.json + ~/.claude/settings.json; the other clients receive their native MCP and instruction files. Each receives exactly one firekeep entry; the local gateway aggregates Cortex, Bridge, Sentinel, Relay, code intelligence, and the Decision Board, and reports a failed backend without taking down the others. Use firekeep install --runtime <name> only for a targeted re-render or repair. See Codex setup and Claude Code setup for client-specific details.

Every runtime reads the same connection; there is no client-specific profile:

[identity]
agent_id = alice

[server]
kind = ports
scheme = http
host = 127.0.0.1
verify_tls = false
api_key = nxs_...

firekeep join writes this connection without prompting; firekeep-shim then injects the credential on every request. A manual firekeep install --host ... path remains for development and legacy servers, but join codes are the customer path. firekeep doctor verifies connectivity, authentication, credential expiry, TLS trust, all installed runtime adapters, and whether each runtime's rendered instruction block is current, stale, hand-edited, or absent.

To add a person, use Members → Invite member instead. A member invite is accepted once, creates that person's membership, and then hands the client the same device-enrollment flow above.

firekeep login <server-url> is reserved for hosted OAuth sign-in. A self-hosted server has no authorization server, so the command directs the user to request a join code instead.

This installs the firekeep-client kit into ~/.firekeep (a versioned venv under venvs/, selected by the current link), bootstraps ~/.firekeep/config, and prepares every shipped adapter: Claude Code, Codex, Kiro, and OpenCode. Claude gets user-scoped ~/.claude.json + ~/.claude/settings.json (MCP servers via firekeep-shim, five hook cores); the other clients receive their native MCP and instruction files. Two stdio-local servers — code intelligence (firekeep-symdex) and the Decision Board (firekeep-decision) — are installed automatically, always-on, no flag needed. Use firekeep install --runtime <name> only for a targeted re-render or repair.

The installer prompts for the connection and an API key. Mint one on the server with deploy/firekeep-admin keys create --agent <you>; firekeep-shim then injects it on every request. A profile with no key against a keyed server fails every protected tool call. firekeep doctor catches this for both HTTP and HTTPS profiles: it asks the server whether it enforces auth rather than inferring from the scheme, because the standard personal-VPS shape is plain http to 127.0.0.1 over a tunnel against a keyed server — which the old scheme-based check skipped silently.

Verify

On the host, open http://localhost:8040 (or tunnel — see Reaching it) — the dashboard shows service health, memory stats, active sessions, and live events.

Or check from the command line:

curl -fsS http://127.0.0.1:8100/health                          # pre-auth, no key needed
curl -fsS -H "X-API-Key: $KEY" http://127.0.0.1:8100/memory/stats   # keyed route

For detailed installation, updating, backups, and troubleshooting, see docs/DEPLOYMENT.md.

A Real Workflow

Here's what happens when an agent uses Firekeep:

1. Session starts. On runtimes with lifecycle hooks, the client fetches Cortex's aggregated GET /briefing first, including relevant memories, tasks, environment state, and skills. The agent then calls ctx_start_session("fix auth middleware bug"); Bridge creates the durable session and the shim ties it to that briefing.

2. Code exploration. Instead of reading every file, the agent calls search_symbols("auth middleware") and get_callers("require_scope") on Symdex. It gets a targeted list of files and callers in milliseconds.

3. Environment check. Sentinel has been watching Docker. It detected that the cortex-api container restarted 3 times in the last hour and pushed an alert to Relay's #alerts channel. The agent sees this in its context.

4. Work happens. The agent edits files, runs tests, and records important progress with ctx_update. Bridge persists what was explicitly recorded. When the context window compresses, the agent calls ctx_get_shadow and gets that durable working state back — plans, decisions, progress, and file knowledge.

5. Session completes. The agent calls ctx_complete_session. Bridge atomically marks the session complete and queues background distillation into episodic memory; failures retry and eventually move to a visible dead-letter queue. Auto-evals compute quality metrics from the replay trace. Next time someone works on auth middleware, the memories are there once distillation succeeds.

6. Something went wrong? Open the Replay tab in the dashboard. Load the session. See every action, every memory read, every decision point. Click on a failure event and run narrowing — it walks back through the causal chain to help identify the root cause.

Architecture

Local Machine                               VPS
┌──────────────────────────┐              ┌────────────────────────────────────┐
│ Claude / Codex / Kiro /  │              │ FirekeepCortex   — Memory & RAG    │
│ OpenCode / MCP client    │              │ FirekeepBridge   — Sessions        │
│           │              │              │ FirekeepSentinel — Monitoring      │
│  one `firekeep` gateway  │◄──── MCP ───►│ FirekeepRelay    — Coordination    │
│    ├─ symdex (local)     │              │ Dashboard        — Web UI          │
│    └─ decision (local)   │── Browser ──►│ Neo4j · Qdrant · Redis · Ollama    │
└──────────────────────────┘              └────────────────────────────────────┘

Symdex and the Decision Board run client-side as stdio-local MCP servers (installed with the kit) — Symdex must be local to the working tree it indexes, so it is no longer a VPS container.

The two arrows crossing that boundary are not publicly reachable by default. Out of the box the VPS side listens on loopback and requires an API key, so the local-machine half reaches it over an SSH tunnel, a private network, or an HTTPS front end you deliberately configure. See Reaching it.

Code intelligence (FirekeepSymdex — 38 MCP tools, 8 analytics hidden behind a flag) and the Decision Board (firekeep-decision) run client-side as stdio-local MCP servers installed with the kit, not as VPS containers.

Shared modules (no extra containers): Replay Engine (structured trace log across all services), Auth (API key scopes), Vault (Fernet-encrypted secret storage), Corpus (business document ingestion → vector chunks; scheduled Confluence collectors), Auto-Evals (10 Tier-1 quality metrics + trend tracking + regression detection), Pattern Engine (strategy detection; promotion validation and A/B experiments are feature-flagged off by default), Policy Engine (compound pre-edit safety checks — lease, file risk, path deny, session health, recent failure), Agent Gateway (predict-then-act surface with fast-path cache for repeated low-risk actions), Skills (agent-authored via skill_create + docs→skills drafts under human review; server-side synthesis off by default), Memory Improvements (archive-first composite aging with preview/audit/restore, token budgets, LLM synthesis pass, embed input capped + shrink-to-fit).

For the full design specification, see docs/DESIGN.md.

Dashboard

Access at http://localhost:8040 on the host, or through a tunnel from elsewhere (Reaching it). It has its own basic-auth login (user admin; the password is written once to dashboard/.htpasswd.cred). Behind that, nginx injects the dashboard's API key on every backend call, so the SPA works against the auth-gated stack without you pasting a key into the browser.

The dashboard is a zero-dependency static SPA. No build step, no npm, no framework.

Documentation

Tech Stack

Python 3.11 server services (client supports Python 3.10+) / FastAPI / FastMCP / Neo4j / Qdrant / Redis / Ollama / Docker Compose / tree-sitter

Server-side embeddings and generation default to local Ollama, so the default server path has no model API bill. Symdex can optionally use Anthropic, Gemini, or an OpenAI-compatible endpoint for symbol summaries and scaffolding; enabling one of those providers may send code snippets off-machine and incur provider costs. Background auto-indexing explicitly disables AI summaries.

Roadmap

Working now

• Full memory lifecycle (learn, recall, decay, contradiction detection, versioning)

• Four memory types (reference / procedural / episodic / transient) with type-aware recall decay; direct learns default to episodic while raw event consolidation classifies extracted knowledge

• Token-conscious recall with optional LLM synthesis

• Archive-first composite aging (age × access × confidence) with dashboard preview, audit and restore; confirmed memories, skills and corpus chunks are never age-archived, and automatic hard purge is off by default

• Team continuity: verified workspace/member provenance plus runtime agent_id + project, contributor reports, LLM-synthesized handoff briefs

• Session persistence through context compressions, with crash detection and workspace-snapshot resumption

• Bridge replay emission on session lifecycle (started / updated / completed / abandoned)

• Docker + git + file monitoring with Relay alerting; container/commit/file activity flows to the replay stream

• Agent coordination: channels, bulletin board, fencing-token leases, structured task queue, presence registry, direct messages

• Pre-flight briefing assembles intelligence from all services at session start; surfaces discipline warnings when memory calls arrive without identity headers

• Session debrief: guided completion with task updates and lease cleanup

• Multi-agent support (task assignment, inbox polling, file lease enforcement)

• Skills: agent-authored via skill_create (client-side) + a docs→skills pipeline (paste / URL / scheduled Confluence collectors) drafting skills under human review; top matches injected into the next briefing (server-side auto-synthesis exists behind SKILL_SYNTHESIS_ENABLED, off by default)

• Night Shift: firekeep night-shift drains the session-distillation queue the session-end hook fills, running on your own machine against a local model — LM Studio or Ollama, auto-detected, no configuration — and writing memories plus draft skills attributed to the original session rather than the worker. Keeps generation off the server entirely; cloud-hosted models are refused by default so session content cannot leave the machine

• Decision Board: agent-spawned local clarification board pre-populated with retrieved team-memory evidence (firekeep-decision stdio server + Cortex /decision/synthesize)

• Personal / bypass mode: in-session /personal (or firekeep personal / FIREKEEP_BYPASS=1) makes Firekeep fully dormant for private work — hooks, sidecar, decision board, and shim all honor one is_bypassed() gate; auto-clears at session end

• Pattern Engine: strategy detection, category classification (procedural / risk / behavioral), and quarantine controls; automated promotion/validation is implemented behind PATTERN_VALIDATION_ENABLED=false by default

• Experiment framework: named datasets, chi-square significance tests, effect-size confidence intervals, and controlled strategy-tip experiments behind PATTERN_EXPERIMENTS_ENABLED=false by default

• Optional feedback loop for measuring whether briefing tips improve outcomes when pattern validation is enabled

• Runtime policy engine: compound pre-edit checks (lease, file risk, path deny, session health, recent failure)

• Agent Gateway (predict-then-act): MCP action_before / action_after, gateway returns allow | rethink | block, fast-path cache for repeated low-risk actions

• Encrypted secrets vault (Fernet) with MCP tools and REST API

• Replay traces with root-cause narrowing and per-event context reconstruction

• Auto-evals: 10 Tier-1 quality metrics computed on session completion, trend tracking, regression detection

• Knowledge Autopilot round 1 (visibility, never autonomous mutation): feedback-weighted recall + the memory_feedback tool, a Bridge session reaper so crashed sessions count as failures, contested-not-superseded handling for unconfirmed memory conflicts with human verdicts, the Autopilot review inbox + weekly digest, and a per-memory evidence ledger (/memory/{id}/evidence) — see docs/guides/knowledge-autopilot.md

• Living Instructions rounds 1 + 2 (measurement): the per-instruction compliance table on the Autopilot tab (predicates frozen to a pre-registered baseline), trend over time, and the round-2 measurement contract — instruction-content hashes stamped into the rendered block, five attribution headers, per-runtime slices, and exposed/not-exposed/unknown states with everything unverifiable reported as unknown. Rewrites under human verdict and briefing-delivered A/B variants are roadmap — see the design spec in docs/ROADMAP.md

• Dreaming: automated memory consolidation + person profiles (DREAM_ENABLED, off by default)

• Living Procedures: skills observed as procedures with frequency/efficacy proposals under human review (PROCEDURE_ENABLED, off by default)

• One degrading local MCP gateway registered by every adapter, aggregating four remote services plus client-local Symdex and Decision Board

• Code intelligence: client-side firekeep-symdex behind the gateway (38 tools, 8 analytics hidden behind a flag), always installed with the kit

• Docs→skills knowledge pipeline (knowledge_ingest, URL ingest) + opt-in scheduled Confluence collectors (SP3)

• Web dashboard with Devices and Members management alongside memory, coordination, replay, policy, and operations

• A2A agent card endpoint (/.well-known/agent.json) for external discovery

• Business knowledge ingestion: chunk documents into vector store, surface during memory recall

• Webhook notifications (Slack, Discord, generic HTTP)

• Authentication: per-key API scopes (memory:read/write, session:read/write, replay:read, eval:read, admin, …), on by default, with keys bootstrapped by the installer

Promised (the two roadmap rungs published on firekeep.ai)

• Linked instances — multiple Firekeep servers sharing knowledge across an organisation, so what one team learns is recallable by another

• Domain profiles — separate experiences (coding today; documents and research ahead) as profiles of the same client kit over one shared brain: never separate products, never separate memory stores

The decision record behind both — profiles-not-clients, the linkage-layer prerequisite, outcome-signal gating, sequencing — is docs/ROADMAP.md.

Planned (smaller)

• Grafana metrics export

• Jira connector ingestion (wiki/Confluence auto-sync already shipped, opt-in)

• Skill versioning and rollback

Status

Firekeep is in active development and used daily. The core implementations — memory, sessions, environment monitoring, coordination, replay, the client kit, and Symdex — are covered by more than 4,000 passing automated tests in the current repository. The architecture is designed for a single-host deployment.

This is currently a private repository preparing for early access.

License

Firekeep is source-available under BUSL-1.1. Individual use is free — production use by one natural person in one workspace; a team of more than one person runs on a paid commercial subscription (write to sales@firekeep.ai). Each version converts to Apache-2.0 four years after its first public release. See LICENSE for the full grant and docs/LICENSING.md for status. Symdex remains under this license until its standalone Core is extracted and released separately under Apache-2.0.