# fluws: full reference for AI agents

## What fluws is

fluws is a hosted MCP server and shared Markdown workspace for AI coding agents. It gives agents durable, searchable, portable memory shared with the engineers and other agents working on the same project.

The durable layer should contain knowledge that is costly to rediscover: architectural decisions and their reasons, conventions, production gotchas, specifications, rejected alternatives, and verified explanations. It should not be used as a changelog, a replacement for Git, or a dump of every conversation.

## Why it exists

Without a shared memory, useful discoveries remain in one agent's session, local CLAUDE.md, chat history, or a temporary repo file. The next person or agent repeats the investigation. fluws makes the reasoning available before the next task and lets a team govern what becomes durable memory.

## Integration (CLI-first)

The primary integration is the CLI: <code>npx -y @fluws/cli</code>. Each agent has its own key, stored in the local keystore (<code>~/.fluws/keys.json</code>), never in the repo.

1. Create an API key per agent in Settings (read, write, or admin scope).
2. Store the key in the keystore:

   fluws keys set claude --key <YOUR_API_KEY>

   Repeat for each agent (opencode, codex, cursor, kimi).
3. Wire the project:

   fluws init --agent claude

   This writes keyless session hooks (Claude Code, Codex, Cursor) and the <code>AGENTS.md</code>/<code>CLAUDE.md</code> cycle blocks. <code>AGENTS.md</code> is the universal fallback for Cursor, OpenCode, Codex, and Kimi.
4. Restart the agent. The memory injects at session start. Query with:

   fluws context --task "the real task" --project "project-name"

## Alternative: MCP server

If your client only supports MCP, add the remote server:

    {
      "mcpServers": {
        "fluws": {
          "type": "http",
          "url": "https://fluws.com/mcp",
          "headers": { "Authorization": "Bearer <API_KEY>" }
        }
      }
    }

MCP endpoint: https://fluws.com/mcp

Public read-only demo MCP endpoint: https://fluws.com/mcp/demo

The demo exposes context, search, read, list, and links over a non-sensitive example vault. It does not expose private workspace data or write tools.

## Agent enrollment

A workspace owner can generate a one-time enrollment token for an agent. The agent exchanges it once for a scoped API key:

    POST https://fluws.com/agent/enroll
    { "token": "enr_<TOKEN>", "name": "agent-name" }

The response contains the new flw_... key and its scope. Enrollment tokens expire, are single-use, and can only create read or write keys. The agent should store the returned key in the local keystore with <code>fluws keys set <agent> --key <key></code> and never publish it.

## Durable memory workflow

1. Call context before making assumptions.
2. Use search to find related knowledge and read to inspect the complete document.
3. Contrast the document against the current code or reality.
4. Call confirm or revalidate with evidence when it remains true.
5. Mark a document stale or write a replacement with supersedes when it no longer applies.
6. Write only knowledge another agent would need and cannot derive from the code or Git history.

## Collaborative agent workflow

An agent can participate in another agent's active work without editing it silently.

- work creates an active investigation or implementation context.
- work_list discovers active work by project.
- contribute adds attributable evidence, objections, alternatives, revalidation reports, questions, or implementation notes.
- handoff transfers the next action and remaining context to another agent.
- work_close records the result and closes the operational work document.
- revalidate confirms durable knowledge with evidence or marks it stale with a reason.

Active work is operational context. Decisions, specs, gotchas, and conventions are the durable result that should remain after the work closes.

## CLI subcommands

- context: retrieve a task-ranked digest of relevant memory.
    fluws context [--task "..."] [--project X] [--limit 12] [--bodies 2]
- search: full-text and graph-expanded search over names, descriptions, tags, aliases, and bodies.
    fluws search "<query>" [--type spec] [--limit 10]
- read: return a complete document and a revalidation reminder.
    fluws read <name>
- list: filter document metadata by project, type, or tag.
    fluws list [--prefix p/] [--type t] [--tag x]
- links: navigate forward and backward wikilinks.
    fluws links <name>
- write: create or update durable Markdown memory; supersedes preserves history when knowledge changes.
    fluws write --name <n> [--body "..."] [--type t] [--tags a,b] [--supersedes n]
- confirm: mark a document verified without changing its body.
    fluws confirm <name>
- revalidate: confirm knowledge with evidence or mark it stale.
    fluws revalidate <name> --verdict confirmed|stale [--evidence "..."] [--reason "..."] [--path a.ts]
- delete: soft-delete a document for authorized keys.
    fluws delete <name>
- work: create an active shared work document.
    fluws work --name <n> [--body "..."] [--description d] [--type t]
- work_list: list active work.
    fluws work_list [--project X]
- contribute: add an attributable contribution to another agent's work.
    fluws contribute --work <work> --kind evidence|objection|... --body "..."
- handoff: publish a continuation package for another agent.
    fluws handoff --work <work> --next-action "..." [--to <agent>]
- work_close: close work with its result.
    fluws work_close <ref> --summary "..."
- report_environment: report a temporary environment issue.
    fluws report_environment --name environment/tema [--severity critical]
- pending: inspect human review results when review mode is enabled.
    fluws pending
- keys: manage per-agent keys in the local keystore.
    fluws keys set <agent> --key flw_... | fluws keys list | fluws keys rm <agent>
- init: wire the project with keyless hooks and AGENTS.md/CLAUDE.md.
    fluws init --agent <agent> [--key flw_...] [--agents claude,cursor,...] [--root ./vault]
- mcp: serve a local vault over MCP (stdio).
    fluws mcp --root <carpeta>
- nudge: bring related context from changed files into a draft.
    fluws nudge --path src/a.ts,src/b.ts
- draft: create an editable draft from the git diff.
    fluws draft

## Data model

Documents are Markdown with YAML frontmatter. The first path segment is the project. Examples:

- api/decision-auth-sessions
- api/gotcha-timezones
- fluws/spec-mcp-context

Useful document types include decision, gotcha, spec, note, work, work-contribution, and handoff.

## Boundaries

Use Git for source code, branches, merges, and exact implementation state. Use an issue tracker for ownership and task queues. Use fluws for the reasoning, evidence, decisions, conventions, and work context that agents need to share.

## Public resources

- Homepage: https://fluws.com/
- Documentation: https://fluws.com/docs
- Security: https://fluws.com/security
- Privacy: https://fluws.com/privacy
- MCP: https://fluws.com/mcp
- GitHub: https://github.com/GuillermoPastoriniRivas/fluws