API Reference

REST endpoints and MCP tools reference

REST Endpoints

POST /ingest

Ingest a pre-distilled memory into the server. Used by client machines to sync memories from local distillation.

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 for the notification service",
    "source_agent": "m4hacbookpro/claude",
    "project": "myproject",
    "memory_type": "episode",
    "privacy": "WORK",
    "source_session": "8036fb63",
    "session_date": "2026-03-27"
  }'

Request fields:

Field	Type	Required	Description
`content`	string	Yes	Memory content (distilled markdown)
`source_agent`	string	No	Machine/agent identifier (default: "remote-client")
`project`	string	No	Project name for filtering
`memory_type`	string	No	One of: episode, lesson, fact, decision (default: episode)
`privacy`	string	No	One of: PUBLIC, WORK, PERSONAL, SENSITIVE (default: WORK)
`source_session`	string	No	Session ID for deduplication
`session_date`	string	No	ISO date when the session happened (default: now)

Response (201):

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

Deduplication: If source_session is provided and memories already exist for that session, the server returns:

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

Auth required: Include Authorization: Bearer <token> header. See Configuration for auth setup. Localhost connections bypass auth. Pro licenses are restricted to single-machine (no remote ingest).

GET /health

Health check endpoint. No auth required.

curl http://localhost:8787/health

Response:

{
  "status": "ok",
  "version": "0.4.0",
  "memories": 473,
  "links": 178,
  "db_size_kb": 4912,
  "llm": "ollama/qwen3.5:9b"
}

MCP Tools Reference

These tools are exposed via MCP protocol (SSE transport at /sse + /messages). Your agent uses them automatically through the registered MCP connection.

hicortex_search

Semantic search across all memories. Uses BM25 + 384-dim vector embeddings with RRF fusion and knowledge graph traversal.

query: string (required) — Natural language search query
limit: number (optional, default: 5) — Max results to return
project: string (optional) — Filter by project name

Returns: Memories with content, composite score, effective strength, memory type, project, and connection count.

hicortex_context

Get recent context memories, optionally filtered by project. Combines recency with knowledge graph traversal. No embedding needed — fast.

project: string (optional) — Filter by project name
limit: number (optional, default: 10) — Max memories to return

Returns: Recent memories with scores and connections.

hicortex_ingest

Store a new memory. Use for important facts, decisions, or lessons the agent wants to remember.

content: string (required) — The memory content to store
project: string (optional) — Project this memory belongs to
memory_type: string (optional) — One of: episode, lesson, fact, decision (default: episode)

Returns: Memory ID confirmation.

hicortex_lessons

Retrieve lessons learned from past sessions. Auto-generated during nightly consolidation from both successes and failures.

days: number (optional, default: 7) — Look back N days
project: string (optional) — Filter by project name

Returns: Array of lesson memories with content and metadata.

hicortex_update

Update an existing memory. If content changes, the embedding is re-computed. Returns before/after diff.

id: string (required) — Memory ID (first 8 chars or full UUID from search results)
content: string (optional) — New content text
project: string (optional) — New project name
memory_type: string (optional) — New type: episode, lesson, fact, decision

Returns: Confirmation with changed fields (before → after).

hicortex_delete

Permanently delete a memory, its vector embedding, and all associated links. Returns the deleted content for audit.

id: string (required) — Memory ID (first 8 chars or full UUID)

Returns: Confirmation with preview of deleted content.

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.