# fluws

> Shared, portable Markdown memory for AI coding agents and engineering teams.

fluws gives every agent its own key, stored in a local keystore. The CLI (<code>npx -y @fluws/cli</code>) wires the project with keyless session hooks and the universal <code>AGENTS.md</code> cycle. It is stored as Markdown, portable to S3 or GitHub, and can require human review before every write.

## Canonical resources

- Homepage: https://fluws.com/
- Documentation: https://fluws.com/docs
- Pricing: https://fluws.com/pricing
- Supported clients: https://fluws.com/integrations
- Use cases: https://fluws.com/use-cases
- Security: https://fluws.com/security
- Privacy: https://fluws.com/privacy
- Full agent reference: https://fluws.com/llms-full.txt
- MCP endpoint: https://fluws.com/mcp
- Public read-only demo MCP: https://fluws.com/mcp/demo
- Public demo guide: https://fluws.com/demo

## Core concepts

- Shared memory for AI coding agents
- Markdown as the portable source of truth
- CLI-first integration (keys in keystore, keyless hooks, AGENTS.md)
- MCP over HTTP for Claude Code, Cursor, OpenCode, Codex, and other MCP clients
- Human review and governance for agent-written memory
- Full-text search expanded through Markdown wikilinks
- Freshness, provenance, confirmation, and superseded documents
- Shared work, agent contributions, evidence, and handoffs

## First integration step (CLI-first)

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

   fluws keys set claude --key <YOUR_API_KEY>

   Repeat for each agent (opencode, codex, cursor, kimi). Keys live in <code>~/.fluws/keys.json</code>, never in the repo.
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>" }
        }
      }
    }

The workspace is selected by the API key. Start each task with <code>context({ task: "the real task", project: "project-name" })</code>.

## 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.

## Source and trust

fluws does not replace Git for source code or issue trackers for task state. It preserves the reasoning, evidence, decisions, and context that should survive a session and be available to the next agent. Read the security page for storage, access, and known limitations.