FirekeepHQ

# Firekeep

**Your agents need more than memory. They need a Keep.**

Firekeep is the **self-hosted operating layer for connected AI agents**. It carries durable knowledge, working context, procedures, coordination, and replayable evidence across sessions, models, machines, and teammates. It connects through MCP today: shipped adapters configure Claude Code, Claude Desktop (auto-detected when the app's config dir exists), Codex, Kiro, and OpenCode, while other MCP clients can use the generic configuration path. 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](https://firekeep.ai) · [Live demo](https://firekeep.ai/?demo=1#cross-runtime-demo) · [Install guide](https://firekeep.ai/docs.html#server) · [Case study](https://firekeep.ai/case-study.html) · [Concepts](https://firekeep.ai/agents-md-vs-memory.html)**

---

## The Problem

AI agents are powerful, but each session starts with partial amnesia. They lose context, repeat discovery, miss operational state, and struggle to explain why they made an earlier decision. When something goes wrong, there is often no reliable trace to inspect. When multiple agents or teammates share a project, coordination becomes fragile.

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

## What Firekeep Does

| Capability | What it means |
|---|---|
| **Memory** | Agents remember what worked, what failed, and what matters across sessions. Semantic + graph retrieval, confidence scoring, contradiction handling, four memory types (reference / procedural / episodic / transient) with type-aware recall decay, recoverable archive-first aging, and token-conscious recall with optional LLM synthesis. Recall is re-ranked by recorded session outcomes (outcome-weighted memory) and by agent feedback on knowledge that was actually acted on (`memory_feedback`). |
| **Knowledge Autopilot** | The knowledge base maintains itself without deciding anything on its own. When two unconfirmed memories genuinely conflict, neither is silently dropped — both stay recallable, marked contested, until a human verdict (`/memory/contested/resolve`). A session reaper closes out crashed/walked-away sessions so failures count in outcome scoring. Every review queue (draft skills, stale skills, procedure proposals, contested pairs, eval dead letters) lands in one inbox with a weekly digest, and `/memory/{id}/evidence` shows every signal behind a memory's rank in one read. |
| **Team Continuity** | Memories carry verified workspace/member provenance plus an untrusted runtime `agent_id` label and project. Per-contributor activity reports and LLM-synthesized handoff briefs let one agent pick up where another left off. |
| **Session Continuity** | Plans, decisions, and progress recorded through the session tools survive context compression. Crashed sessions are auto-detected on next start and offered for resumption with a periodic workspace snapshot (git branch, recent commits, diff stats) embedded in the shadow. |
| **Environment Awareness** | Configured Docker, git, and file collectors monitor operational state instead of relying only on prompts. Container restarts, new commits, and file changes flow into a replayable event stream. |
| **Agent Coordination** | Shared channels, bulletin board, structured task queue, resource leases with monotonic fencing tokens, presence registry, and direct messages. Concurrent agents can assign work, track progress, and use leases to prevent overlapping edits; hook-enabled clients block an edit when another agent already holds the file lease. |
| **Predict-then-Act Gateway** | Agents declare intent before consequential actions (`action_before` → `allow | rethink | block`), then reconcile outcomes (`action_after`). Combines a runtime policy engine (lease, file risk, path deny, session health, recent failure) with a fast-path cache for repeated low-risk actions. |
| **Skills** | Agents author reusable "what to do when X happens" playbooks via the `skill_create` tool (client-side, with full session context); a docs→skills pipeline drafts more from wikis/runbooks under human review. Top matches are injected into the next session's briefing. (Server-side auto-synthesis exists behind `SKILL_SYNTHESIS_ENABLED` but is off by default — the CPU-only deploy can't run the generation LLM in workable time.) |
| **Enforced Runbooks** | A skill whose steps carry command matchers is a runbook a human can arm: `advise` (round-1 advisories), `require_ack` (a matched command is challenged and proceeds only after an audited acknowledgement — one-use permit bound to workspace, member, session, command hash, step, bundle version and execution), or `block` (fails closed, with a server receipt the client requires before honoring an allow). Evidence is scored by *success* — a step counts only when its command exits 0 — and every enforcement event lands in a deviation ledger (dashboard + inbox), storing command hashes, never command text. Modes are set by a human on an admin-only route; agents can propose runbooks, never arm them. Opt-in via `PROCEDURE_ENABLED`, currently being dogfooded on our own deploys — see [docs/guides/living-procedures.md](docs/guides/living-procedures.md). |
| **Decision Board** | When a clarification needs more than a couple of questions, the agent opens a local browser board pre-populated with evidence retrieved from team memory — better questions, informed by what the team already learned. The local gateway fronts the Decision Board process and Cortex `/decision/synthesize`. |
| **Living Instructions** | The instruction layer measures itself: a per-instruction compliance table computed deterministically from replay (did sessions recall before answering, record as they went, declare consequential actions), with trend over time, per-runtime slices, and exposure receipts — sessions carry a content hash of the instruction text that actually reached them, and anything unverifiable reports as *unknown* rather than counted. Honest about its limits by construction: it measures behavior, not whether the behavior helped. Fleet-drafted rewrites under human verdict and A/B validation are roadmap. |
| **Trust Ledger** | A per-agent employment record built from the declarations agents already make through the gateway (`action_before`/`action_after`): declared-action count, reconciliation rate, prediction-match calibration (Brier over stated confidence vs reconciled outcome), reversals, sessions, first/last seen. Visibility only — it reports, it never gates. Honest by construction: calibration is behavior not competence, only declared actions are seen, `agent_id` is a self-reported label so the record is per declared identity, and calibration reads *not enough signal* below a threshold rather than inventing a number. The enforcing half (a capability broker turning the record into earned autonomy) is roadmap. |
| **Auto-Evals + Pattern Discovery** | Quality metrics computed from replay traces on session completion. Pattern detection is enabled; automated promotion/validation and A/B experiment endpoints are implemented but disabled by default until a deployment has enough session volume to use them responsibly. |
| **Replay & Explainability** | Every memory read/write, session lifecycle event, environment change, coordination action, and gateway decision is recorded as a structured trace. Inspect, narrow, and reconstruct context at any prior event. |
| **Encrypted Secrets** | Fernet-backed vault for infrastructure credentials, API tokens, and connection strings. Distinct from memory — secrets never appear in recall. |
| **Business Knowledge** | Ingest company documents (wiki pages, tickets, API docs) — manually, or via scheduled Confluence collectors. Chunks land in the vector store and surface naturally during memory recall alongside operational memories. |
| **Code Intelligence** | Tree-sitter-based symbol search, caller graphs, architecture maps, and impact analysis that returns symbol slices instead of whole files — runs **client-side** through the local gateway (`firekeep-symdex` is installed with the kit). 38 MCP tools (8 analytics tools hidden by default behind `SYMDEX_ANALYTICS_ENABLED`). |

## Why Firekeep Is Different

Firekeep is not another chatbot wrapper or prompt orchestration layer.

It is an **operating layer for connected AI 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.
- **Deep where the work happens.** Coding is the strongest shipped workflow, with Symdex for code intelligence. It is not the product boundary: Docdex brings selected document folders into the same Keep, Maildex brings a member's email (read-only IMAP, always member-private, `firekeep maildex add`), and the shared continuity, coordination, governance, and evidence layers are domain-independent.
- **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](https://modelcontextprotocol.io/) tools through one local `firekeep` stdio gateway. Shipped adapters configure Claude Code, Claude Desktop, 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](https://github.com/google/A2A) agent