Skip to content

api-reference.md

Latest commit

 

History

History
292 lines (208 loc) · 7.84 KB

api-reference.md

File metadata and controls

292 lines (208 loc) · 7.84 KB
Raw

API Reference

All endpoints require the Authorization: Bearer <CORTEX_SECRET> header unless noted otherwise.

Base URL: http://127.0.0.1:7100 (default)

Provider Endpoints

Used by agent frameworks (Hermes, OpenClaw) for automatic memory injection.

POST /provider/prefetch

Get a formatted memory context block for prompt injection. Zero-LLM, 5–15 ms.

curl -X POST http://127.0.0.1:7100/provider/prefetch \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","messages":["What port is the proxy running on?"],"context_remaining":500}'

Request body:

Field Type Required Description
agent string yes Agent identity
messages string[] yes Recent conversation messages for context extraction
context_remaining number no Max tokens for memory block (default: 500)

Response: Memory block with HOT facts (full text) and WARM stubs (recall IDs).

POST /provider/sync

Record an agent turn as an L0 event. Non-blocking (< 1 ms).

curl -X POST http://127.0.0.1:7100/provider/sync \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","session":"sess_123","content":"User asked about Redis config","type":"exchange","source_type":"user_authored"}'

POST /provider/compress

Get L1 summaries for in-session context window compaction.

Requires agent AND session. L1 records are served only to their owning agent+session (Invariant 2) — ids belonging to another agent or session are silently excluded (replaced by markers). Max 500 turns.

curl -X POST http://127.0.0.1:7100/provider/compress \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","session":"sess_123","turns":[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]}'

POST /provider/session_end

Signal end of session. Triggers dreaming pipeline (background insight extraction).

curl -X POST http://127.0.0.1:7100/provider/session_end \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","session":"sess_123"}'

MCP Endpoints

Agent-facing pull retrieval. All serve L2 facts only (L0/L1 never exposed).

POST /mcp/query

Search memory with full graph activation + count-rule gate.

curl -X POST http://127.0.0.1:7100/mcp/query \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"query":"Redis configuration","limit":10,"agent":"default"}'

Response:

{
  "facts": [
    {"id":"fact_abc","text":"Redis 7.2 deployed as session cache...","confidence":0.7,"source_type":"user_authored","injection_status":"inject"}
  ],
  "entity_count": 3,
  "activated_nodes": 8,
  "elapsed_ms": 6.2
}

POST /mcp/search

Simple BM25 full-text search on L2 facts (no graph activation). Only live facts (confidence > 0) within the caller's visibility: shared scope plus the caller's own agent:<agent> scope. Optional agent (default: daemon's CORTEX_DEFAULT_AGENT). Note: the shared secret is the only credential — the agent parameter selects visibility, it is not per-agent authorization.

curl -X POST http://127.0.0.1:7100/mcp/search \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"query":"nginx proxy","limit":10,"agent":"default"}'

GET /mcp/fact/:id

Get a single L2 fact by ID. Supports ref_N aliases from warm stubs (session-scoped, 24h TTL — pass agent and session as query params). Returns 403 when the fact belongs to another agent's private scope.

curl "http://127.0.0.1:7100/mcp/fact/fact_abc123?agent=default&session=sess_123" \
  -H "Authorization: Bearer $SECRET"

POST /mcp/remember

Store a fact directly in L2 (bypasses L0/L1 pipeline). Trust is enforced server-side regardless of payload claims (memory-poisoning defense): the fact is always stored as source_type: agent_internal, confidence capped at 0.4, scope agent:<agent> (private to the writer). Entities are extracted from the text when not provided. Near-duplicates (AUDN: shared entity + jaccard ≥ 0.3, live and visible facts only) return the existing id with duplicate: true instead of creating a copy.

curl -X POST http://127.0.0.1:7100/mcp/remember \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"fact_text":"Redis runs on port 6379 with maxmemory 2GB","entities":["Redis"],"agent":"default"}'

POST /mcp/observe

Record a raw L0 observation (will be consolidated by background pipeline).

curl -X POST http://127.0.0.1:7100/mcp/observe \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","session":"sess_123","content":"Deployed Redis 7.2","type":"exchange","source_type":"tool_result"}'

GET /mcp/timeline

Chronological L2 facts for an entity.

curl "http://127.0.0.1:7100/mcp/timeline?entity=Redis&limit=20" \
  -H "Authorization: Bearer $SECRET"

Query params: entity (required), limit, from (timestamp ms), to (timestamp ms)

GET /mcp/graph/neighbors/:nodeId

Get a graph node and its edges.

curl http://127.0.0.1:7100/mcp/graph/neighbors/node_redis \
  -H "Authorization: Bearer $SECRET"

GET /mcp/graph/activate

Run spreading activation on given entities, return activated nodes.

curl "http://127.0.0.1:7100/mcp/graph/activate?entities=Redis,PostgreSQL" \
  -H "Authorization: Bearer $SECRET"

GET /mcp/slots/:agent/:key

Read a slot value.

curl http://127.0.0.1:7100/mcp/slots/default/session_context \
  -H "Authorization: Bearer $SECRET"

PUT /mcp/slots/:agent/:key

Write a slot value.

curl -X PUT http://127.0.0.1:7100/mcp/slots/default/active_task \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"value":{"task":"deploy redis","priority":"high"}}'

Admin Endpoints

GET /health

System health check. No authentication required.

curl http://127.0.0.1:7100/health

Response:

{"status":"ok","schema_version":8,"graph_nodes":1500,"uptime_ms":86400000}

GET /stats

Record counts at each level.

curl http://127.0.0.1:7100/stats \
  -H "Authorization: Bearer $SECRET"

Response:

{"l0":44000,"l1":6800,"l2":28000,"graph_nodes":15000}

POST /admin/reload-graph

Reload graph from SQLite into memory (after manual DB changes).

curl -X POST http://127.0.0.1:7100/admin/reload-graph \
  -H "Authorization: Bearer $SECRET"

POST /admin/consolidate

Trigger consolidation manually (runs in background).

curl -X POST http://127.0.0.1:7100/admin/consolidate \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"modules":["l0l1","l1l2"]}'

Modules: l0l1, l1l2, l2l3

GET /admin/l3/pending

List pending L3 rule proposals.

curl http://127.0.0.1:7100/admin/l3/pending \
  -H "Authorization: Bearer $SECRET"

POST /admin/l3/approve/:id

Approve a pending L3 rule (makes it live).

curl -X POST http://127.0.0.1:7100/admin/l3/approve/rule_abc \
  -H "Authorization: Bearer $SECRET"

DELETE /admin/l3/reject/:id

Reject and delete a pending L3 rule.

curl -X DELETE http://127.0.0.1:7100/admin/l3/reject/rule_abc \
  -H "Authorization: Bearer $SECRET"

POST /admin/supersession/apply/:vid

Apply a supersession verdict (zero the old fact).

curl -X POST http://127.0.0.1:7100/admin/supersession/apply/sv_123 \
  -H "Authorization: Bearer $SECRET"

POST /admin/supersession/skip/:vid

Skip a supersession verdict (keep both facts).

curl -X POST http://127.0.0.1:7100/admin/supersession/skip/sv_123 \
  -H "Authorization: Bearer $SECRET"