DeepBlue Dynamics / Docs / Ferricula / API Reference

API Reference

HTTP endpoints on :8765. All bodies JSON.

POST /remember requires a pre-computed embedding vector. If you're using the arena Python SDK, embedding is handled automatically. If calling the API directly, use any embedding service (1536-dim recommended).

Memory operations

Endpoint	Purpose
`POST /remember`	Ingest a memory — `id`, `vector`, `tags`, `importance`, `keystone`
`POST /recall`	Vector cosine search — returns ranked memories
`POST /search`	BM25 keyword search
`POST /hybrid`	Combined vector + BM25 search
`DELETE /delete/:id`	Remove a memory and all its edges
`GET /get/:id`	Raw memory row — tags, vector dimension
`GET /inspect/:id`	Full thermodynamic detail — fidelity, heat, state, graph degree
`GET /maxid`	Next available ID

POST /remember

curl -X POST http://localhost:8765/remember \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "vector": [0.12, -0.04, 0.31, 0.08, -0.22],
    "tags": {
      "text": "The best products make you feel something.",
      "channel": "hearing"
    },
    "importance": 0.8
  }'

Response:

{"remembered": true, "id": 1}

POST /recall

curl -X POST http://localhost:8765/recall \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.08, -0.02, 0.29, 0.11, -0.19],
    "k": 5,
    "channel": "hearing"
  }'

Response: array of memories ranked by cosine similarity, filtered through resonance gates.

[
  {
    "id": 1,
    "fidelity": 0.847,
    "tags": {"text": "The best products make you feel something.", "channel": "hearing"},
    "score": 0.934
  }
]

GET /inspect/:id

curl http://localhost:8765/inspect/1

Response:

{
  "id": 1,
  "fidelity": 0.847,
  "heat": 0.12,
  "state": "Active",
  "recalls": 7,
  "importance": 0.8,
  "keystone": false,
  "graph_degree": 3,
  "tags": {"text": "The best products make you feel something.", "channel": "hearing"}
}

Graph operations

Endpoint	Purpose
`POST /connect`	Create a labeled edge between two memories
`POST /disconnect`	Remove an edge
`GET /neighbors/:id`	Graph neighbors and edge labels
`GET /inversion/:id`	Check inversion status

POST /connect

curl -X POST http://localhost:8765/connect \
  -H "Content-Type: application/json" \
  -d '{
    "from": 1,
    "to": 2,
    "label": "inspired_by"
  }'

Response:

{"connected": true}

GET /neighbors/:id

curl http://localhost:8765/neighbors/1

Response:

{
  "id": 1,
  "neighbors": [
    {"id": 2, "label": "inspired_by", "direction": "outgoing"},
    {"id": 5, "label": "contradicts", "direction": "incoming"}
  ]
}

Identity / system state

Endpoint	Purpose
`GET /status`	Memory counts, graph stats, prime tree
`GET /identity`	Full identity — heat, archetype activations, resonance gates
`GET /clock`	Current clock tick
`GET /tools`	Active tool surface, load tier, suppressed list
`POST /keystone/:id`	Toggle keystone immunity on a memory
`POST /checkpoint`	Flush state to disk

GET /identity

curl http://localhost:8765/identity

Response:

{
  "name": "Steve Jobs",
  "cognitive_heat": 3.8,
  "archetypes": {
    "Intuition": {"active": true, "gate": "Resonating"},
    "Ethics": {"active": true, "gate": "Resonating"},
    "Advocate": {"active": true, "gate": "Fidelity > 0.3"},
    "Fortune": {"active": true, "gate": "Heat < 8.0"},
    "Craft": {"active": true, "gate": "Load < 0.9"}
  }
}

GET /tools

curl http://localhost:8765/tools

Response:

{
  "tier": "ELEVATED",
  "heat": 4.2,
  "load_score": 0.61,
  "escalate": false,
  "tools": [
    "memory_recall",
    "memory_search",
    "memory_remember",
    "memory_status"
  ],
  "suppressed": [
    "memory_dream",
    "memory_connect",
    "memory_disconnect",
    "memory_keystone"
  ]
}

GET /status

curl http://localhost:8765/status

Response:

{
  "total_memories": 247,
  "active": 198,
  "ghosts": 12,
  "keystones": 37,
  "edges": 84,
  "clock": 1042
}

Dream / entropy

Endpoint	Purpose
`POST /dream`	Trigger a dream cycle — decay, consolidate, prune, ghost echoes
`POST /offer`	Feed raw entropy hex — drives dream threshold
`GET /dream/latest`	Last dream cycle report

POST /dream

curl -X POST http://localhost:8765/dream

Response:

{
  "dreamed": true,
  "decayed": 198,
  "consolidated": 5,
  "pruned": 3,
  "keystoned": 2,
  "heat_before": 4.2,
  "heat_after": 1.7
}

POST /offer

curl -X POST http://localhost:8765/offer \
  -H "Content-Type: application/json" \
  -d '{"entropy": "a1b2c3d4e5f6a7b8c9d0"}'

Response:

{"accepted": true, "accumulated": 0.72, "threshold": 1.0}

When accumulated reaches threshold, the next offer triggers a dream automatically.

Language / reflection

Endpoint	Purpose
`POST /confer`	Voice quality check — hedging, assistant patterns, verbosity, authenticity
`GET /terms`	BM25 vocabulary terms
`GET /glossary`	Full term glossary
`GET /skg`	Semantic keyword graph overview
`GET /skg/:term`	SKG neighbors for a specific term

POST /confer

curl -X POST http://localhost:8765/confer \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I think maybe we could potentially consider looking into this."
  }'

Response:

{
  "hedging": 0.82,
  "verbosity": 0.65,
  "assistant_patterns": 0.21,
  "authenticity": 0.34,
  "pass": false,
  "notes": ["excessive hedging", "low authenticity score"]
}

The Craft archetype uses /confer results as a resonance gate at CRITICAL load — if voice quality is poor, the response is blocked.

Quick reference

Method	Path	Body
POST	/remember	id, vector, tags, importance, keystone?
POST	/recall	vector, k, channel
POST	/search	query, k, channel
POST	/hybrid	vector, query, k, channel
DELETE	/delete/:id	-
GET	/get/:id	-
GET	/inspect/:id	-
GET	/maxid	-
POST	/connect	from, to, label
POST	/disconnect	from, to
GET	/neighbors/:id	-
GET	/inversion/:id	-
GET	/status	-
GET	/identity	-
GET	/clock	-
GET	/tools	-
POST	/keystone/:id	-
POST	/checkpoint	-
POST	/dream	-
POST	/offer	entropy
GET	/dream/latest	-
POST	/confer	text
GET	/terms	-
GET	/glossary	-
GET	/skg	-
GET	/skg/:term	-

Enterprise deployments and source licensing: hello@deepbluedynamics.com