# Clove — API & MCP Reference
# https://cloveos.com/docs
# Plain text for LLM consumption. Two single-binary services: clove-kb (memory) + rust-kernel (agent runtime).

## Overview
clove-kb      :9090*  Memory — append-only log + FTS/vector/graph. REST · MCP · gRPC · web UI.
clove-kernel  :8080   Agent runtime — jobs, sandbox policy, graph runtime, optimizer. HTTP + MCP.
* clove-kb default is :8080; run on :9090 locally to avoid clashing with the kernel.
The kernel reaches memory by registering clove-kb as a native HTTP-MCP server (no bridge, no sidecar).

## Quick start
# 1) memory (clove-kb) on :9090
cd rust-kb && cargo build --release -p kb-server
CLOVE_KB_HTTP_ADDR=127.0.0.1:9090 CLOVE_KB_ADDR=127.0.0.1:50051 ./target/release/clove-kb
curl localhost:9090/v1/health        # -> {"log_head":0}
# 2) kernel on :8080, pointed at the kb
cd rust-kernel && cp .env.example .env   # set CLOVE_KB_URL=http://127.0.0.1:9090 + a model key
./start.sh
curl localhost:8080/api/mcp/servers      # -> clove-kb registered over HTTP-MCP
# Docker (clove-kb):
docker run -d -p 9090:8080 -e CLOVE_KB_API_KEY=secret clove-kb:dev

## Auth & namespaces
clove-kb : Authorization: Bearer <CLOVE_KB_API_KEY> on /v1/* (except GET /v1/health, GET /ui).
kernel   : Authorization: Bearer <CLOVE_API_KEY> on /api/* (except /api/health).
Omit the key for open dev mode. clove-kb data lives under a namespace; reads are scoped self | descendants.

## clove-kb — REST API (JSON, epoch-ms timestamps)
  GET    /v1/health                  Liveness -> {log_head}. No auth.
  GET    /v1/stats                   Counts, projector lag, embedder/LLM flags.
  POST   /v1/notes                   Remember. {namespace,actor,text,importance,keywords,tags} -> {seq,ref_id}.
  POST   /v1/append                  Low-level event append.
  POST   /v1/recall                  Hybrid recall. {q,ns,scope,limit,token_budget} -> {segments,...}.
  GET    /v1/recall                  Same via query params.
  GET    /v1/notes/search            Keyword (BM25). ?ns=&q=&limit=
  GET    /v1/notes/list              Recent notes. ?ns=&limit=&offset=
  GET    /v1/graph                   Subgraph -> {nodes,edges}. ?ns=&scope=&q=
  GET    /v1/episodes                Recent sessions. ?ns=&limit=
  GET    /v1/episodes/:id            Episode members.
  GET    /v1/communities             Clusters + AI summaries.
  POST   /v1/communities/rebuild     Recompute. ?ns=&scope=
  POST   /v1/forget                  Soft-delete. ?ref_id= one | ?ns= namespace.
  GET    /v1/state/:ns/:key          Read working-memory value.
  POST   /v1/state/:ns/:key          Set working-memory value. {value, ttl_epoch_ms}.
  GET    /ui                         Web console (observe/put/retrieve). No auth.

# Remember
curl -X POST localhost:9090/v1/notes -H "Authorization: Bearer secret" -H 'Content-Type: application/json' \
  -d '{"namespace":"workspace:acme/notes","actor":"alice","text":"Alice is allergic to peanuts","importance":0.6,"tags":["health"]}'
# Recall
curl -X POST localhost:9090/v1/recall -H "Authorization: Bearer secret" -H 'Content-Type: application/json' \
  -d '{"q":"what can alice not eat?","ns":"workspace:acme","scope":"descendants","limit":8,"token_budget":4000}'
Recall is local (bge-small embed + FTS + graph) — no LLM key needed. The smart layer (entities/summaries) is opt-in, on the build path.

## clove-kb — MCP (native JSON-RPC 2.0 at POST /mcp and POST /)
  kb_recall(q, namespace?, scope?, limit?)            Hybrid recall -> ranked context.
  kb_graph(q?, namespace?, scope?)                    Connected subgraph (multi-hop).
  kb_add_note(text, namespace?, tags?)                Save a memory.
  kb_search_notes(q, namespace?, limit?)              Keyword search.
  kb_list_notes(namespace?, limit?, offset?)          List recent notes.
  kb_episodes(namespace?, limit?)                     List recent sessions.
  kb_forget(ref_id? | namespace?)                     Soft-delete.
  kb_state_set(namespace, key, value, ttl_epoch_ms?)  Store working-memory value.
  kb_state_get(namespace, key)                        Read working-memory value.
  kb_stats()                                          Counts + projector lag.
  kb_health()                                         Liveness.

# Pair Claude Code:
claude mcp add --transport http clove-kb https://kb-acme.example.com/mcp --header "Authorization: Bearer <token>"
# Verify:
curl -s -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' https://kb-acme.example.com/mcp
# Pair the kernel: just set CLOVE_KB_URL (+ CLOVE_KB_KEY) — it registers clove-kb over HTTP-MCP at boot. No bridge.

## clove-kb — gRPC
KnowledgeBrain service (proto/kb.proto): Append, Recall, StateGet, StateSet, Subscribe, Health. Bearer auth (Health exempt).

## rust-kernel — REST API (under /api, bearer CLOVE_API_KEY except /api/health)
  GET    /api/health                          Version, queue depth, MCP servers, status. No auth.
  POST   /api/jobs                            Submit job {agent_name,workspace_id,goal,model,budget_usd,max_steps,allowed_tools,sandbox_id}.
  GET    /api/jobs/:id                         Job state + result.
  DELETE /api/jobs/:id                         Cancel.
  GET    /api/jobs/:id/events                  SSE stream of RunEvents.
  GET    /api/jobs/:id/event-log               Durable cursor replay.
  GET|POST /api/workspaces                     Workspaces (tenant roots).
  GET|POST /api/projects                       Project alias over workspaces.
  GET|POST /api/sandboxes                       Sandbox policy (allowed_wikis, network, daily cap, kill switch).
  POST   /api/sandboxes/:id/agents             Bind an agent to a sandbox.
  GET|POST /api/agents                          Agent definitions.
  GET    /api/runs                             Agent run records.
  GET    /api/run-outcomes/:job_id             Outcome + attribution (cost, tokens, tools, memory refs).
  POST   /api/run-outcomes/:job_id/feedback    Human quality feedback.
  GET    /api/cost                             Cost by agent/model/workspace/day.
  GET    /api/audit-events                     Structured audit feed.
  GET|POST /api/watchers                        External-signal watchers (poll/webhook/MCP).
  GET    /api/healer-actions                   Auto-proposed fixes (+ /:id/approve|reject).
  GET    /api/optimizer-proposals              Policy/agent change proposals (+ /:id/approve|promote|reject|rollback).
  GET|POST /api/skills                          Skill registry; POST /api/skills/mine forges skills from runs.
  GET    /api/mcp/servers                      Registered MCP servers (incl. clove-kb).
  GET    /api/mcp/servers/:name/tools          Tools exposed by a server.

# Submit + stream a job
curl -X POST localhost:8080/api/jobs -H 'Content-Type: application/json' \
  -d '{"agent_name":"BISMO","workspace_id":"grova","sandbox_id":"grova-ops","goal":"Use kb_retrieve to find when the launch is, then answer.","model":"claude-haiku-4-5","budget_usd":0.10,"max_steps":4,"allowed_tools":["kb_retrieve"]}'
curl -N localhost:8080/api/jobs/<id>/events

## rust-kernel — MCP (the kernel is an MCP consumer)
Set CLOVE_KB_URL (+ CLOVE_KB_KEY); at boot the kernel posts initialize/tools/list to clove-kb's /mcp over HTTP and
registers it (transport="http", no Node bridge; legacy bridge behind CLOVE_KB_MCP_BIN). Agents reach memory via the
kb_retrieve tool, scoped to the sandbox's allowed_wikis. Successful runs are mirrored back with kb_add_note.
  curl localhost:8080/api/mcp/servers              -> {"servers":["filesystem","clove-kb"]}
  curl localhost:8080/api/mcp/servers/clove-kb/tools -> kb_recall, kb_graph, kb_add_note, ... (11 tools)
Other MCP servers (GITHUB_TOKEN / SLACK_BOT_TOKEN / LINEAR_API_KEY) auto-register at boot when their token is set.