MuninnDB

REST API Reference

Base URL: http://localhost:8475/api

The REST API is the primary interface for scripts, web clients, and any language without a native SDK. All endpoints accept and return JSON.

Authentication

Authenticated endpoints require a Bearer token in the Authorization header. Tokens are created via muninn init or the admin API.

Authorization: Bearer mk_xK9m...

Public endpoints (/health, /ready, /workers, /hello) require no auth. All vault operations require a Bearer token.

Engrams

POST /engrams

Store a new engram in a vault.

{
  "vault":      "default",
  "concept":    "user prefers dark mode",
  "content":    "Always render UI in dark theme",
  "tags":       ["preference", "ui"],
  "confidence": 0.9
}

Returns: { "id": "01JN..." }

GET /engrams/{id}

Fetch a single engram by ULID. Pass vault as a query param: ?vault=default

Returns full Engram object including temporal priority data (access count, last access), confidence, and associations.

DELETE /engrams/{id}

Soft-delete an engram. It is archived, not permanently removed (restorable for 7 days via MCP).

GET /engrams

List engrams in a vault (paginated). Query params: vault, limit, offset, tags.

GET /engrams/{id}/links

Get all associations for a specific engram.

Activation

POST /activate

Primary retrieval endpoint. Runs the full 6-phase cognitive pipeline — BM25 scoring, temporal priority scoring, Hebbian boosting, and graph traversal.

{
  "vault":       "default",
  "context":     ["what does the user prefer?"],
  "max_results": 10,
  "threshold":   0.5,
  "max_hops":    2
}

Returns array of engrams with score, concept, content, why (score breakdown), and hop_path.

POST /link

Create an explicit weighted association between two engrams. Links are traversed during Activate to surface related memories.

{
  "vault":     "default",
  "source_id": "01JN...",
  "target_id": "01JN...",
  "rel_type":  5,
  "weight":    0.8
}

rel_type values:

1 supports · 2 contradicts · 3 depends_on · 4 supersedes · 5 relates_to · 6 is_part_of · 7 causes · 8 preceded_by · 9 followed_by · 10 created_by_person · 11 belongs_to_project · 12 references · 13 implements · 14 blocks · 15 resolves

User-defined types start at 0x8000.

Vaults

GET /vaults

List all vaults with their engram counts and storage sizes.

GET /stats

Vault statistics: engram count, confidence distribution, storage bytes, coherence scores. Pass ?vault=default.

Streaming (SSE)

GET /subscribe text/event-stream

Server-Sent Events stream. Receive push notifications whenever new engrams are stored or existing ones are activated above a threshold. Pass vault as query param.

GET /session text/event-stream

Long-lived SSE stream of session activity — a running log of activations, writes, and link events for the current session.

Health & Stats

GET
/health

Liveness probe. Returns 200 when the server is up. No auth required.

GET
/ready

Readiness probe. Returns 200 when all workers are initialized. No auth required.

GET
/workers

Worker statistics — Hebbian worker, confidence worker, contradiction worker status. No auth required.

← Previous Next →