API Reference

Authentication

All endpoints except /health require a bearer token:

Authorization: Bearer <your-auth-token>

The token is generated during npx @gamaze/hicortex init and stored in ~/.hicortex/config.json. To find it on a running server:

npx @gamaze/hicortex status

Localhost bypass: Requests from 127.0.0.1 / ::1 bypass auth. The token is only enforced for remote callers (clients on other machines).

REST Endpoints

POST /distill canonical capture

Submit a denoised session for server-side distillation. The server runs the LLM distillation pipeline, embeds the resulting memories, and stores them. Raw session content is discarded after processing.

This is the endpoint used by the nightly pipeline on both server-mode and client-mode machines. Client machines denoise locally (no LLM — strip tool noise, truncate bulk I/O) then POST here; raw session content never leaves the originating machine.

curl -X POST http://localhost:8787/distill \
  -H "Authorization: Bearer <your-auth-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "# Session transcript (denoised)\n\n...",
    "session_id": "8036fb63",
    "session_date": "2026-07-01",
    "source_agent": "mymachine/claude",
    "project": "myproject",
    "privacy": "WORK"
  }'

Request fields:

Body size limit: 25 MB.

Responses:

GET /health

Health check. No auth required.

curl http://localhost:8787/health

Response:

{
  "status": "ok",
  "version": "0.11.0",
  "memories": 3026,
  "links": 4272,
  "db_size_kb": 10528,
  "llm": "ollama/qwen3.5:14b",
  "mode": "server"
}

When running in recall-only mode (no LLM): "llm": null and "mode": "recall-only".

GET /search

Semantic memory search. Used by MCP tools and the Hermes/OC plugins for recall.

curl "http://localhost:8787/search?query=authentication+architecture&limit=5&project=myproject" \
  -H "Authorization: Bearer <your-auth-token>"

Query params: query (required), limit (default: 5), project (optional filter), privacy (optional filter).

GET /context

Recent context memories for a project. Combines recency with knowledge graph traversal. No embedding needed — fast.

curl "http://localhost:8787/context?project=myproject&limit=10" \
  -H "Authorization: Bearer <your-auth-token>"

GET /lessons

Returns the lessons block and memory index. Used by the CC SessionStart hook to inject lessons into context at session start.

curl "http://localhost:8787/lessons" \
  -H "Authorization: Bearer <your-auth-token>"

GET /index

The knowledge domain index — which domains exist and how many memories and lessons each holds. Useful for an agent to orient before searching.

curl "http://localhost:8787/index" \
  -H "Authorization: Bearer <your-auth-token>"

GET /graph

Knowledge-graph queries. The op parameter selects the operation:

curl "http://localhost:8787/graph?op=export&domain=Work&limit=1000" \
  -H "Authorization: Bearer <your-auth-token>"

For export: nodes are ranked by effective (decayed) strength and capped by limit (default 5000, max 10000); edges are included only when both endpoints made the cut. Each node carries its domain tags ordered by association weight. domain= filters by a memory's primary domain; tag= matches any tag at any weight — "everything touching X".

GET /viz

The interactive knowledge-graph page (3D with a 2D toggle) — feeds on /graph?op=export. Fully self-contained: all rendering libraries are served by your own daemon from GET /viz/vendor/<file> (strict allowlist), zero external requests.

open "http://localhost:8787/viz"

The page shell itself contains no data, so it is served without auth (like /health); all memory content comes from the bearer-only /graph endpoint. From localhost no token is needed. From a remote browser, paste the auth token into the in-page prompt once (stored in localStorage), or open /viz?token=<your-auth-token> — the page strips the token from the URL on load.

POST /ingest legacy

Ingest a single pre-distilled memory. Retained for backward compatibility with older client-mode installs. New integrations should use /distill instead.

curl -X POST http://localhost:8787/ingest \
  -H "Authorization: Bearer <your-auth-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Session Memory: 2026-03-27 - myproject\n\n## Decisions Made\n- Adopted event-driven architecture",
    "source_agent": "mymachine/claude",
    "project": "myproject",
    "memory_type": "episode",
    "privacy": "WORK",
    "source_session": "8036fb63",
    "session_date": "2026-03-27"
  }'

Request fields:

Response (201):

{ "id": "8470ef8f-64ab-4e28-bfc8-1624b195b2be", "message": "Memory ingested" }

Deduplication: If source_session is provided and memories already exist for that session:

{ "id": null, "skipped": true, "existing_count": 3 }

MCP Transport

MCP tools are exposed via SSE transport at GET /sse + POST /messages. Your agent uses them automatically through the registered MCP connection — you do not call these endpoints directly.

MCP Tools Reference

8 tools available via MCP. Used automatically by the agent; you can also invoke them explicitly.

Server Configuration

Default port is 8787. Override via CLI:

npx @gamaze/hicortex server --port 9000 --host 0.0.0.0

Or set in ~/.hicortex/config.json. See Configuration for all options.