§ Connect · bring flmnt memory into your tools

Wire any agent to a live MCP.

One authenticated endpoint. Sign in as yourself and flmnt connects you to your workspaces — pick your client below, then switch between workspaces just by asking your agent.

No workspace yet
Create a workspace to connect.

flmnt scopes memory to a workspace, and your MCP endpoint is minted per workspace. Create one first — until then there is no endpoint for an agent to connect to.

§ 01Choose your client

What are you connecting?

§ 02Set up · Claude Code

Three ways in.

Register flmnt as an HTTP MCP server with Claude Code’s own “claude mcp add” command, or by hand in .mcp.json. The flmnt CLI is a separate tool that automates that and installs the full automation kit — a lifecycle hook map, 13 /flmnt-* slash commands, and tool permissions — so reading and recording memory happen on their own.

1
Register the server with claude mcp add
claude code
terminal
claude mcp add --transport http --scope project flmnt "http://localhost:8000/mcp"
--scope project writes it to .mcp.json so the whole repo inherits it. Drop the flag for a private, machine-local server.
2
Approve sign-in
Run [/mcp] inside Claude Code and approve the flmnt OAuth sign-in. Claude Code connects to the endpoint directly — no extra tooling.
§ 03After you connect

What your agent gets.

23 MCP tools · 3 families

Every connected client sees the same toolset — identical whether you came in through Claude Code, a connector, or a JSON config. Your agent reads recent context, retrieves causally across the graph, and writes back decisions, keyframes, and mistakes. The full surface:

01

Discovery & reading

orient · inspect · replay · 10 tools

Cheap, deterministic reads. Use these to find streams, inspect their shape, and pull raw entries by position or time — no model in the loop.

list_workspaces
list_workspaces()
List the workspaces you can reach — your entitled set.
Returns
Array of { id, name, ownerTeamName, isOwner }.
When
Call when the target workspace is ambiguous, then operate in the one you pick.
list_streams
list_streams(project_id?)
List every stream in a project — your first orientation call.
Parameters
project_idstringoptionalDefaults to the active workspace; pass to target another entitled workspace.
Returns
Array of { id, name, type, version, entryCount, tokenSize }.
When
Start here when you don’t yet know which stream holds what you need.
get_stream_metadata
get_stream_metadata(stream_id)
Shape and stats for a single stream, without reading its contents.
Parameters
stream_idstringrequired
Returns
{ type, topology, version, entryCount, lastKeyframe }.
peek_stream
peek_stream(stream_id, limit=10)
The latest N entries from a known stream. The fastest read path.
Parameters
stream_idstringrequired
limitintdefault 10How many recent entries to return.
Returns
The most recent entries, newest last. No filtering or ranking.
slice_events
slice_events(stream_id, start_pos?, end_pos?, start_time?, end_time?)
Read an exact window — by position range or by ISO timestamp range.
Parameters
stream_idstringrequired
start_posintoptionalInclusive start index.
end_posintoptionalExclusive end index.
start_timeISO 8601optionalLower time bound.
end_timeISO 8601optionalUpper time bound.
Returns
Every entry inside the window, in order.
When
Pass a position range or a time range — not both. Built for replay and auditing.
search_events
search_events(stream_id, query)
Full-text search scoped to one stream.
Parameters
stream_idstringrequired
querystringrequired
Returns
Matching entries ranked by lexical relevance.
get_graph_neighborhood
get_graph_neighborhood(stream_id, entry_id, depth=2)
Walk the causal graph outward from one entry.
Parameters
stream_idstringrequired
entry_idstringrequired
depthintdefault 2How many edge-hops to traverse.
Returns
Nodes and CAUSED_BY edges within depth hops of the entry.
When
The primitive behind “why did this happen?” — trace a decision back to what caused it.
read_keyframe
read_keyframe(stream_id, position?)
Read a session checkpoint — current state, open threads.
Parameters
stream_idstringrequired
positionintoptionalOmit for the latest keyframe.
Returns
The keyframe’s full content at that position.
read_plan
read_plan(stream_id, position?)
Read an implementation-plan snapshot.
Parameters
stream_idstringrequired
positionintoptionalOmit for the latest plan.
Returns
The plan snapshot’s full content.
get_hydration_status
get_hydration_status(job_id)
Poll an artifact-ingestion job to completion.
Parameters
job_idstringrequired
Returns
{ status } — pending · running · done · failed.
When
Pair with hydrate_artifact, which returns the job_id.
02

Context materialization

RLM-built context windows · 2 tools

The two model-backed reads. Instead of raw entries, the Recurrent Language Model assembles a coherent, token-budgeted context window for your agent to start from.

materialize_context
materialize_context(token_budget=4000, stream_id?)
A coherent snapshot of recent context — no query needed.
Parameters
token_budgetintdefault 4000Hard ceiling on the returned window.
stream_idstringoptionalScope to one stream; omit for a cross-stream project snapshot.
Returns
A RLM-assembled context block that fits the budget.
When
Use at the start of a session to load “where things stand” without asking a question.
query_context
query_context(query, …)
Query-driven causal retrieval — the heavy, precise read.
Parameters
querystringrequiredWhat you’re trying to find or understand.
optionalAdditional ranking / scope options; confirm against the live schema.
Returns
Ranked, fully-hydrated context plus recent mistakes near the landing point.
When
The RLM orients on the query, fans out the causal graph, ranks lexical + embedding, then hydrates full content.
03

Writing

checkpoint · decide · record · 11 tools

How memory accrues. Each call appends to a typed, append-only stream. Some writes are causal-ref gated — they refuse to record unless you tie the entry to what caused it.

write_keyframe
write_keyframe(stream_id, content, causal_refs=[])
Checkpoint current understanding and state.
Parameters
stream_idstringrequired
contentstringrequiredThe checkpoint — state, open threads, next steps.
causal_refsentry_id[]default []Entries this state followed from.
Returns
The new entry’s id and position.
When
Drop one at the end of any working session so the next can resume.
record_plan
record_plan(stream_id, content)
Append an implementation-plan snapshot to a plan stream.
Parameters
stream_idstringrequired
contentstringrequired
Returns
The new plan entry’s id and position.
record_decisioncausal-ref gated
record_decision(stream_id, content, causal_refs=[], acknowledge?)
Record a confirmed planning decision — product, architecture, strategy.
Parameters
stream_idstringrequired
contentstringrequiredThe decision and its rationale.
causal_refsentry_id[]default []What this decision was based on.
acknowledgebooloptionalExplicitly proceed with no refs.
Returns
The new entry — or a causal_ref_required error.
When
Gated: with no refs and no ack it records nothing. Forces decisions to carry their “why.”
record_operational_decision
record_operational_decision(content, causal_refs=[])
Record an operational / execution decision — the day-to-day fixes.
Parameters
contentstringrequired
causal_refsentry_id[]default []
Returns
The new entry on the operational stream.
When
No gate, and no stream_id — it targets the operational stream automatically.
record_mistake
record_mistake(content, target_entry_id?, was_corrected=false)
Record a mistake or error to the dedicated mistake stream.
Parameters
contentstringrequiredWhat went wrong, and why.
target_entry_identry_idoptionalA prior mistake this corrects.
was_correctedbooldefault falseFlip a prior mistake to corrected.
Returns
The new (or updated) mistake entry.
When
Drives the dashboard’s Mistake Correction Rate.
record_exploration
record_exploration(stream_id, content)
Record a tentative idea or hypothesis for later follow-up.
Parameters
stream_idstringrequired
contentstringrequired
Returns
The new exploration entry.
record_metric
record_metric(stream_id, metric_name, value, labels={})
Append an operational metric.
Parameters
stream_idstringrequired
metric_namestringrequired
valuenumberrequired
labelsobjectdefault {}Dimensions to slice on.
Returns
The recorded metric point.
record_supersession
record_supersession(stream_id, content, supersedes)
Record a decision that replaces a prior one, creating a SUPERSEDED_BY edge.
Parameters
stream_idstringrequired
contentstringrequiredThe new, superseding decision.
supersedesentry_idrequiredEntry id of the decision being replaced.
Returns
The new decision entry plus the typed edge.
When
Retrieval surfaces the superseder, so a stale decision is never served as current. Drives Decision Stability.
record_attestation
record_attestation(kind, note="")
Attest that recalled context changed the outcome — a ContextAttestation metric.
Parameters
kindstringrequiredWhat kind of attestation this is.
notestringdefault ""What the context was, and how it changed the outcome.
Returns
The recorded attestation metric (value 1).
create_stream
create_stream(stream_type, name, topology={})
Provision a new stream.
Parameters
stream_typeenumrequiredOne of the stream types below.
namestringrequired
topologyobjectdefault {}Optional graph/partition config.
Returns
The new stream’s id and metadata.
hydrate_artifact
hydrate_artifact(content, content_type="text")
Submit a document for ingestion into the graph.
Parameters
contentstringrequired
content_typestringdefault "text"Format hint for the ingester.
Returns
{ job_id, status } — poll with get_hydration_status.

Stream types

Every write lands on a typed, append-only stream. The stream_type you pass to create_stream is one of these:

domain
planning decisions & explorations
operational
execution decisions
mistake
errors & corrections
plan
implementation-plan snapshots
metrics
operational metrics
keyframe
per-session checkpoints
conversation
session transcript
Plus conversation (session transcript) and the dashboard’s own write-only streams, which aren’t for agent use.
§ 04Claude Code · automation kit

How recording becomes automatic.

This is the kit flmnt setup installs for you — the same way we run flmnt in our own repo. A project prompt so every session knows what to record, a full lifecycle hook map so reading and recording memory happen on their own, and a set of /flmnt-* slash commands for the on-demand writes. Here is what it wires, so you can see (and trim) it.

A
Add a project prompt
CLAUDE.md
# flmnt memory

This repo records to the **your** workspace via MCP.

- Record a **decision** whenever you commit to an approach (and why).
- Drop a **keyframe** at the end of any working session — current state, open threads.
- Capture a **mistake** the moment a run regresses, with the cause.

Read recent keyframes before starting work. Memory persists across sessions.
B
The keyframe-gate hook
simplest hook
.claude/settings.local.json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "flmnt gate" }
        ]
      }
    ]
  }
}
The minimal single hook — a memory-recency gate on every prompt. flmnt setup installs this plus the full map below.
C
The full lifecycle hook map
setup installs this

Claude Code fires hooks at lifecycle moments — session start, every prompt, after a tool runs, on stop, on subagent stop, before a compact, at session end. flmnt setup maps flmnt CLI commands onto all of them so memory reads and writes happen on their own. It also wires nudge scripts on UserPromptSubmit and a hard-block causal-ref gate on record_decision. The command map:

Hook · commandWhat it does
SessionStart
flmnt brief
Inject a recent-context brief — latest keyframes, open threads, recent mistakes — so the session starts oriented.
SessionStartbest-effort
flmnt health
Fail fast if Core, Engine, or the proxy aren’t reachable before the agent starts writing.
UserPromptSubmit
flmnt gate
Keyframe-recency gate. If memory is stale, nudge the agent to read or checkpoint before it acts.
PostToolUsebest-effort
flmnt record-metric --hook
Emit a CI/throughput metric for the command that just ran, so the dashboard sees live activity.
PreCompact
flmnt derive --write
Checkpoint open threads and derive before the context window is compacted, so nothing essential is dropped.
SubagentStopbest-effort
flmnt derive --hook
Capture a subagent’s reasoning when it stops, not just the main turn.
Stop
flmnt derive --hook
Derive decisions, keyframes, and mistakes from the finished turn and record them automatically.
SessionEndbest-effort
flmnt derive --write
A final derive at clean session exit, as a deterministic backstop.
SessionEndbest-effort
flmnt sync push
Push the session’s local data up to the workspace when the session ends.
Excerpt · the settings.local.json shape
.claude/settings.local.json
{
  "hooks": {
    "SessionStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "flmnt brief" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "flmnt gate" }] }
    ],
    "Stop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "flmnt derive --hook" }] }
    ]
  }
}
Hooks run shell commands, so anything in the CLI is fair game. Check exact flags with flmnt <command> -h.