FirekeepHQ

# Firekeep

## Your agents shouldn’t work like strangers.

Connect Claude Code, Codex, Kiro, OpenCode, and other MCP clients through one
shared, self-hosted Keep.

Every solved problem should make the next one easier. Firekeep preserves the
experience behind the work — durable knowledge, working state, procedures,
coordination, and inspectable evidence — and puts it back to work in the next
session, tool, or machine.

Use it for your own continuity on one workstation. Add teammates when you need
them without starting the team’s context over.

**[Website](https://firekeep.ai/?src=github) · [Install](https://firekeep.ai/docs.html?src=github#server) · [Product tour](https://firekeep.ai/?src=github#outcomes) · [Firekeep Studio](https://firekeep.ai/?src=github#studio) · [Evidence](https://firekeep.ai/?src=github#proof) · [Privacy](https://firekeep.ai/privacy.html) · [Support](https://github.com/kapella-hub/FirekeepHQ/issues)**

---

## One Keep, across runtimes

```mermaid
flowchart LR
    A["Claude Code<br/>stores a proven fix"] --> K[("your self-hosted<br/>Keep")]
    K --> B["Codex<br/>recalls the fix + evidence"]
    K --> C["Kiro<br/>reuses the procedure"]
    K --> D["OpenCode / MCP client<br/>continues informed"]
```

Agents keep their native interfaces and provider-owned sessions. What carries
forward is the Firekeep context they explicitly record and recall through the
same local MCP gateway. That means one person can switch tools without losing
the thread, and a team can earn context once and carry it forward.

**[See Claude Code and Codex share one Keep →](https://firekeep.ai/claude-code-codex-shared-memory.html?src=github)**

## Install Firekeep

The installer configures Claude Code, Codex, Kiro, and OpenCode together (plus
Claude Desktop when its config directory exists), then asks where your Firekeep
server should live. The full setup flow is in the
**[install guide](https://firekeep.ai/docs.html#server)**.

```bash
curl -fsSL 'https://firekeep.ai/latest/install?src=github' | sh    # macOS / Linux
irm 'https://firekeep.ai/latest/install.ps1?src=github' | iex      # Windows PowerShell
```

The current server targets `linux/amd64` and needs Docker Compose v2, two x86-64
CPU cores, and Git; 16 GB RAM is recommended for the default stack. It binds to
`127.0.0.1` by default. See the
**[requirements and sizing notes](https://firekeep.ai/docs.html#requirements)**
before choosing a host.

**Trying Firekeep for the first time? [Share what worked and where you got stuck →](https://github.com/kapella-hub/FirekeepHQ/discussions/15)**

## Runtime coverage

- **Client Kit:** configures Claude Code, Codex, Kiro, and OpenCode together;
  Claude Desktop is added when its config directory exists. Other MCP clients
  can use the generic path.
- **Claude Code:** managed MCP, instructions, and lifecycle hooks. Its supported
  pre-tool hook can hard-block an edit, write, or shell action.
- **Codex:** managed MCP plus `AGENTS.md` guidance. Codex exposes no native hooks,
  so lifecycle automation and pre-edit enforcement are not implied.
- **Kiro CLI:** a named Firekeep agent with MCP, steering, and lifecycle hooks.
  On the validated Kiro CLI 2.12.1 surface, its pre-edit hook is advisory.
- **Firekeep Studio:** runs Codex, Claude Code, Kiro CLI, and Grok in one desktop
  workspace. The direct Grok adapter has no Keep memory, hooks, or briefing;
  Studio reports that boundary instead of inheriting another runtime’s status.

See the **[integration guide](docs/INTEGRATIONS.md)** and
**[Studio runtime matrix](studio/README.md#runtime-support)** for the maintained
details.

## Measured retrieval, with the method attached

On the accepted 2026-08-28 LongMemEval-S run, Firekeep achieved **97.7% Evidence
Recall@10**: at least one labeled evidence session appeared in the first ten
results for **459 of 470 scored questions**. The measurement covers retrieval,
not generated-answer accuracy; it is one corrected deterministic run rather
than a multi-run confidence interval.

**[Methodology](https://firekeep.ai/benchmarks/METHODOLOGY.md) · [Result data](https://firekeep.ai/benchmarks/longmemeval-s-20260828.json)**

## The problem Firekeep solves

People do not build professional judgment by rereading every email, document,
ticket, or source file from the beginning. They remember what happened, why a
decision worked, how a failure was diagnosed, and which procedure held up in
practice. That experience changes how they approach the next problem.

Agents should improve the same way. Firekeep connects the knowledge, working
state, coordination, and evidence behind the work so the next agent can begin
with the experience the last one earned.

## Detailed capability map

| 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. |
| **Fleet-as-GPU (Night Shift)** | The connected agents' own machines do the knowledge base's homework overnight, against a local model, and only ever produce drafts. The session-end hook queues a distill job per session; the server's nightly passes queue one job per stale skill (*re-author it*) and per contested memory pair (*propose a verdict*); `firekeep night-shift` drains the queue — started for you at session start whenever LM Studio or Ollama is listening. A human still activates every draft and resolves every pair, and an approval-rate ledger per job type on the Autopilot tab says whether the fleet's work is worth keeping. |
| **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 a