flmntLog inRequest access

flmnt → connect your agents

Wire any agent to a live MCP.

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

Your MCP server URL

https://mcp.production.flmnt.ai/mcp

01 · five minutesConnect an agentRegister the MCP endpoint in the client you already use. Nothing to install.02 · optionalAutomate recordingInstall the toolchain so Claude Code records without being asked.03 · for productsBuild on the SDKAssemble context and write decisions from inside your own application.

Memory is scoped to a workspace and the endpoint is minted per workspace, so create one before you connect — until then there is nothing for an agent to sign in to.

Step 01 · choose your client

What are you connecting?

Every client reaches the same endpoint and sees the same toolset. Only the registration format differs.

Step 02 · set up

Every client, one endpoint.

Pick a client above and its steps appear here. Every route registers the same endpoint — the commands below already have it filled in.

Claude Code

01

Register the server

claude mcp add --transport http --scope project flmnt "https://mcp.production.flmnt.ai/mcp"

--scope project writes it to .mcp.json so the whole repo inherits it. Drop the flag for a private, machine-local server.

02

Approve sign-in

Run /mcp inside Claude Code and approve the OAuth sign-in. Claude Code connects to the endpoint directly — no extra tooling.

03

Optional: the automation kit

Claude Code is the only client with lifecycle hooks, so it's the only one that can record without being asked. That's step 04 below.

Reference · after you connect

What your agent gets: 23 tools, three families.

Every connected client sees the same toolset, whichever route you came in through. Your agent reads recent context, retrieves causally across the graph, and writes back decisions, keyframes and mistakes. You don't need to read this list to start — your agent discovers the tools itself.

Discovery & reading10 tools · orient · inspect · replay

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

  • list_workspacesThe workspaces you can reach.
  • list_streamsEvery stream in a project — the first orientation call.
  • get_stream_metadataShape and stats without reading contents.
  • peek_streamThe latest N entries. The fastest read path.
  • slice_eventsAn exact window, by position range or timestamp range.
  • search_eventsFull-text search scoped to one stream.
  • get_graph_neighborhoodWalk the causal graph outward from one entry — the primitive behind "why did this happen?"
  • read_keyframeA session checkpoint: current state, open threads.
  • read_planAn implementation-plan snapshot.
  • get_hydration_statusPoll an ingestion job to completion.
Context materialization2 tools · model-assembled windows

The two model-backed reads. Instead of raw entries, these assemble a coherent, token-budgeted context window for your agent to start from.

  • materialize_contextA coherent snapshot of recent context, no query needed. Takes a token budget as a hard ceiling. Use at session start to load where things stand.
  • query_contextQuery-driven causal retrieval — the heavy, precise read. Orients on the query, fans out the causal graph, ranks lexically and by embedding, then hydrates full content. Returns ranked context plus recent mistakes near the landing point.
Writing11 tools · checkpoint · decide · record

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.

  • record_decisionA confirmed planning decision. Gated: with no refs and no acknowledgement it records nothing, which forces decisions to carry their why.
  • record_supersessionA decision that replaces a prior one, creating a typed edge. Retrieval surfaces the superseder, so a stale decision is never served as current.
  • record_operational_decisionDay-to-day execution decisions. No gate, and it targets the operational stream automatically.
  • record_mistakeWhat went wrong and why. Can mark a prior mistake corrected.
  • write_keyframeCheckpoint state and open threads. Drop one at the end of any session so the next can resume.
  • record_planAn implementation-plan snapshot.
  • record_explorationA tentative idea or hypothesis, for later follow-up.
  • record_metricAn operational metric with labels to slice on.
  • record_attestationAttest that recalled context changed the outcome.
  • create_streamProvision a new typed stream.
  • hydrate_artifactSubmit a document for ingestion into the graph.
Stream types7 types · the stream_type for create_stream
  • domainPlanning decisions and explorations. Written by record_decision and record_exploration.
  • operationalDay-to-day execution decisions. Written by record_operational_decision, which targets it automatically.
  • mistakeErrors and their corrections. Written by record_mistake.
  • planImplementation-plan snapshots. Written by record_plan, read by read_plan.
  • metricsOperational metrics with labels. Written by record_metric.
  • keyframePer-session checkpoints. Written by write_keyframe, read by read_keyframe.
  • conversationSession transcript.

Step 04 · Claude Code · automation kit

How recording becomes automatic.

Three commands and recording runs on its own — the same way we run flmnt in our own repo. flmnt setup writes the project prompt, the lifecycle hooks and the slash commands into your repo for you.

A

Install the toolchain

The hooks below call flmnt as a bare command, so install it globally and it's on the PATH for every hook and every repo.

npm install -g @mmmnt/flmnt

B

Sign in

Authenticate the CLI against your workspace endpoint. Both login and setup take the server URL.

flmnt login --server-url https://mcp.production.flmnt.ai/mcp

C

Run setup

This installs the kit: the lifecycle hook map, the slash commands and the tool permissions. Everything below is what it writes — shown so you can see it, and trim it. Name the workspace this repo records into — its name, not an id — and every hook targets it regardless of which workspace the CLI is pointed at elsewhere. Without it a repo falls back to whichever workspace the machine was last pointed at, which is how one project's sessions end up recorded in another's.

flmnt setup --server-url https://mcp.production.flmnt.ai/mcp --project your-workspace

That's it — you're connected

Everything below is written for you by flmnt setup. You don't need to author any of it, and you don't need to read it to start working. It's here so you can see what landed in your repo and change or remove any of it later.

What setup wrote into your repoaudit or trim it · nothing to do

D

A project prompt written by setup

Setup writes this into CLAUDE.md. It is a short, static instruction for what to record — not a place decisions live.

# flmnt memory

This repo records to the 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.

E

The keyframe-gate hook written by setup

The smallest piece of the kit, shown on its own: a memory-recency gate on every prompt. If memory is stale it nudges the agent to read or checkpoint before it acts. Setup installs this along with the full map below.

{
  "hooks": {
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "flmnt gate" }] }
    ]
  }
}

F

The full lifecycle hook map written by setup

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. Setup maps CLI commands onto all of them and wires a hard-block causal-ref gate on record_decision. This is the table of what it wired, for when you want to audit or trim it.

Hook · commandWhat it does
SessionStartflmnt briefInject a recent-context brief — latest keyframes, open threads, recent mistakes — so the session starts oriented.
SessionStartflmnt healthbest effortFail fast if the services aren't reachable before the agent starts writing.
UserPromptSubmitflmnt gateKeyframe-recency gate. If memory is stale, nudge the agent to read or checkpoint before it acts.
PostToolUseflmnt record-metric --hookbest effortEmit a throughput metric for the command that just ran, so the dashboard sees live activity.
PreCompactflmnt derive --writeCheckpoint open threads and derive before the context window is compacted, so nothing essential is dropped.
SubagentStopflmnt derive --hookbest effortCapture a subagent's reasoning when it stops, not just the main turn.
Stopflmnt derive --hookDerive decisions, keyframes and mistakes from the finished turn and record them automatically.
SessionEndflmnt derive --writebest effortA final derive at clean session exit, as a deterministic backstop.
SessionEndflmnt sync pushbest effortPush the session's local data up to the workspace when the session ends.

Hooks run shell commands, so anything in the CLI is fair game. Check exact flags with flmnt <command> -h.

Why this matters for the recordThe gate on record_decision is the mechanism behind the rest of the site: a decision that can't say what it was based on doesn't get recorded. And record_supersession is what makes a replaced decision stop being served while staying readable as history.

Step 05 · building your own product

The SDK is a different route in.

MCP connects the agents you already run. The SDK is for products you're building — you assemble context before a model call and write back what the exchange decided after it. Same record, different entry point, and neither requires the other.

01

Install the SDK

npm install @mmmnt/flmnt-sdk

README →npm →

02

Issue an API key

A key (flmnt_sk_…) is issued by a workspace owner or admin. Open the workspace the product should read and write, then use its API Connections action.

Workspaces →Your profile →

The key exchanges at the broker for a 15-minute token. There is no refresh token — the SDK re-exchanges automatically, which means revoking a key ends access within one token lifetime. No interactive OAuth, because the SDK runs inside your application rather than on a developer's machine.

03

Connect in code

FLMNT_API_KEY=flmnt_sk_…   # .env, never committed
import { connect, acquireToken, queryContext, recordEntry } from '@mmmnt/flmnt-sdk';

connect({
  brokerTokenUrl: 'https://oauth.production.flmnt.ai/token',
  graphqlUrl: 'https://api.production.flmnt.ai/graphql',
});
await acquireToken(process.env.FLMNT_API_KEY);

const { result } = await queryContext({ query: 'why did the deploy fail', tokenBudget: 4000 });
await recordEntry({ streamId: `${workspaceId}::domain`, content: 'Use PostgreSQL', kind: 'decision' });

Point the SDK at the two production endpoints, then exchange your key. Keep the key in the environment, never in the repo.

Worked examples

Every method returns the operation's field value untouched, so what you get back is what the router answered.

Retrieve context for a task

const { result } = await queryContext({
  query: 'why did the deploy fail',
  tokenBudget: 4000,
});

materializeContext is the same operation with an empty query — use it when you want the current picture rather than an answer to a question.

Record a decision

await recordEntry({
  streamId: `${workspaceId}::domain`,
  content: 'Use PostgreSQL',
  kind: 'decision',
});

Stream ids are workspaceId::streamType — your workspace id joined to one of the stream types in step 03.

Replace a decision

await recordSupersession({ /* the new decision, and what it replaces */ });

This is what stops the old decision being served while keeping it readable as history.

Handle a refusal

import { GraphRefusedError, WireNetworkError } from '@mmmnt/flmnt-sdk';

try {
  const { result } = await queryContext({ query, tokenBudget: 4000 });
} catch (err) {
  if (err instanceof GraphRefusedError) {
    // the router declined, in its own words — surface it, don't paper over it
  } else if (err instanceof WireNetworkError) {
    // already retried once; the wire is down
  }
}

A refusal is never returned as a fabricated answer, which is the behaviour you want when the result feeds a model.

The full surfaceevery exported method
  • queryContext · materializeContextRetrieval.
  • listStreams · getStreamMetadata · peekStreamOrientation reads.
  • searchEvents · sliceEvents · getNeighborhoodSearch, exact windows, causal graph walks.
  • readKeyframe · readPlanCheckpoints and plan snapshots.
  • recordEntry · writeKeyframe · recordMistakeThe common writes.
  • recordSupersession · recordPlan · recordMetric · createStreamSupersession, plans, metrics, provisioning.
  • setWireBackendTransport override, for tests.

README and full signatures →Package on npm →

What it won't doThe SDK never reshapes what the router answers — each method returns the operation's field value untouched. A refusal arrives in the router's own words as a GraphRefusedError; a dead wire is retried once and then surfaces as a WireNetworkError, never as a fabricated answer.

Which route do I want?If your team runs Claude Code, Cursor or Codex against a project, that's MCP — steps 01 to 04 above, no SDK required. If you're shipping an AI product of your own and want control over what goes into each model call, that's the SDK. For builders →

One endpoint, every agent

Create a workspace, then point your agents at it.

Switching workspaces later is a question you ask your agent, not a reconfiguration.

Request accessBuilding your own product?