Orient
context · search · listDiscover what exists and what is relevant to the current task.
SHARED MEMORY FOR CODING AGENTS
Your team's knowledge,
ready before every task.
fluws gives every agent its own key, stored in a local keystore. The CLI (npx -y @fluws/cli) wires the project with keyless session hooks and the universal AGENTS.md cycle. It is stored as Markdown, portable to S3 or GitHub, and can require human review before every write.
01 CLI-first02 Portable Markdown03 Optional review
01 · CONNECT
30-second integration (CLI-first)
No install needed: the CLI runs with npx. Each agent authenticates with its own key, stored in your local keystore (~/.fluws/keys.json), never in the repo.
1. Create a key per agent in Settings → copy it
fluws keys set claude --key YOUR_API_KEY
# opencode, codex, cursor, kimi: each agent gets its own key2. Wire the project (hooks + AGENTS.md)
fluws init --agent claudeReady. Restart the agent: the memory injects at session start. Run
fluws context --task "..." to query.Prefer an MCP server? Add
fluws to your client's MCP config with https://fluws.com/mcp and Authorization: Bearer YOUR_API_KEY.No account yet? Try the public read-only demo: connect your client to
https://fluws.com/mcp/demo without an API key.02 · FIRST CALL
Start with context
Before reading files or proposing changes, check what the team already learned. Pass the real task so the index prioritizes what is relevant.
CLI call
fluws context --task "add webhook authentication" --project apiWHAT IT RETURNSAn actionable digest
Relevant decisions, conventions, gotchas, and specs. It does not return the whole vault or burn unnecessary context.
12 docs by default
bodies on demand
review verdicts included
03 · OPERATING MODEL
One memory, three layers of work
fluws separates finding knowledge, reading it, and changing it. That keeps responses small and makes the actions that mutate shared memory explicit.
Understand
read · linksRead the full document and explore its neighborhood in the graph.
Preserve
write · confirm · revalidateRecord new knowledge or verify that existing knowledge is still current.
04 · STRUCTURE
Design memory that can be found
The first segment of the name is the project. There is no parallel catalog to maintain, and the same convention works on the web, in storage, and for agents.
Naming convention
project/document-name
api/decision-auth-jwt
api/gotcha-timezones
fluws/spec-mcp-contextOne idea per documentEasier to search, verify, and replace.
Links, not duplicatesUse
[[wikilinks]] to connect related context.Describe the whyThe code shows what it does; memory should explain why.
05 · DOCUMENTS
Markdown with useful metadata
The body stays Markdown, readable in any editor. The frontmatter provides signals for search, freshness, provenance, and governance.
decision a choice and its reasongotcha a mistake expensive to repeatspec a stable specificationnote a research note or referenceapi/gotcha-timezones.md
---
type: gotcha
tags: [cron, timezones]
---
# Cron jobs and timezones
Cron jobs run in UTC, not local time.
See [[api/deploy-checklist]] before touching schedules.06 · FRESHNESS
Memory needs maintenance too
01Write
Record what was hard to discover and another agent would need to know.
02Connect
Link documents with wikilinks so the graph extends search.
03Confirm
After checking it against the code, use confirm, even if it is not yet stale.
04Replace
If it changed, use revalidate to mark it obsolete or write with supersedes. History records both actions.
07 · HUMAN CONTROL
Governance without friction for the team
Turn on review mode in the workspace and agent writes and deletes go to a queue. A human can approve, edit, or reject with a note. The verdict comes back inside context, so the agent does not repeat a rejected proposal.
Agent proposes→Pending diff→Human decides→Live memory
08 · AUTOMATION
Make the protocol automatic
Run fluws init --agent agent to wire keyless session hooks (Claude Code, Codex, Cursor) and the universal AGENTS.md cycle block. The hook command is npx -y @fluws/cli context --hook client; the CLI resolves the key from ~/.fluws/keys.json. AGENTS.md is the universal fallback for Cursor, OpenCode, Codex, and Kimi.
.claude/settings.local.json
{
"hooks": {
"SessionStart": [{
"hooks": [{
"type": "command",
"command": "npx -y @fluws/cli context --hook claude"
}]
}]
}
}Pair the hook with operational rules so the agent knows when to write:
CLAUDE.md · AGENTS.md · system prompt
## Shared fluws memory
This project uses fluws to share decisions, conventions, and gotchas between agents and engineers.
1. At the start of a task, call context with task and project.
2. Before writing memory, use search to avoid duplicates.
3. When you discover something another agent needs to know, use write.
4. When you verify a document is still valid, use confirm.
5. When a decision replaces another, use supersedes in write.
6. When another agent is already working on the topic, use work, contribute, and handoff to continue without repeating the investigation.
7. When memory has changed, use revalidate with evidence or mark it stale.
Write only knowledge that was hard to discover and is not in the code, the git log, or the immediate task context.09 · REFERENCE
CLI & MCP reference
The CLI (npx -y @fluws/cli) is the primary integration. The remote MCP server (https://fluws.com/mcp) is also available for clients that prefer the MCP protocol. Tool visibility depends on your API key's scope. A read-only key does not expose write tools; an admin key can delete via soft-delete. Work and handoffs let an agent take part in another agent's investigation without silently editing it.
context--task "..." [--project X] [--limit 12] [--bodies 2]Returns the relevant index of decisions, conventions, gotchas, and specs. This is the recommended first call.
search"<query>" [--type spec] [--limit 10]Searches name, description, tags, aliases, and body. Search also propagates through wikilinks.
read<name>Reads the full frontmatter and body of a document.
list[--prefix p/] [--type t] [--tag x]Lists metadata filtered by prefix, type, or tag.
links<name>Returns forward-links and backlinks of the document.
write--name <n> [--body "..."] [--type t] [--tags a,b] [--supersedes n]Creates or updates memory. With review mode on, proposes the change instead of applying it.
confirm<name>Marks a document as verified without changing its content.
revalidate<name> --verdict confirmed|stale [--evidence "..."] [--reason "..."] [--path a.ts]Confirms knowledge with evidence or marks a document as obsolete.
delete<name>Recoverable soft-delete. Only available to credentials with admin scope.
work--name <n> [--body "..."] [--description d] [--type t]Opens active work another agent can continue.
work_list[--project X]Lists active work to avoid duplicate investigations.
contribute--work <work> --kind evidence|objection|... --body "..."Adds evidence, objections, alternatives, or notes to another agent’s work.
handoff--work <work> --next-action "..." [--to agent]Transfers the next action and remaining context to another agent.
work_close<ref> --summary "..."Closes work and keeps its result in history.
report_environment--name environment/tema [--severity critical]Reports a temporary environment issue.
pendingShows pending agent changes and the outcome of previous reviews.
nudge--path src/a.ts,src/b.tsBrings related context from changed files into a draft.
draftCreates an editable draft from the git diff.
NEXT STEP
Connect your first agent
Create a workspace, generate an API key, and come back to this guide to try context. Your first useful memory can be the decision your team just made.