API Reference

Sulcus exposes a REST API at https://api.sulcus.ca. All SDKs are thin HTTP wrappers over these endpoints.

Authentication

Every request requires a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.sulcus.ca/api/v1/agent/nodes

Get your API key from the Sulcus Dashboard.

Memories

Store a Memory

POST /api/v1/agent/nodes

Example:

{
  "label": "User prefers dark mode and monospace fonts",
  "memory_type": "preference",
  "is_pinned": true,
  "key_points": ["dark mode", "monospace", "UI preference"]
}

List Memories

GET /api/v1/agent/nodes?page=1&page_size=25

Get a Memory

GET /api/v1/agent/nodes/:id

Update a Memory

PATCH /api/v1/agent/nodes/:id

Delete a Memory

DELETE /api/v1/agent/nodes/:id

Note: Locked memories (is_locked: true) cannot be deleted. Unlock first via PATCH.

Search

Semantic Search

POST /api/v1/agent/search

{
  "query": "dark mode preferences",
  "limit": 10
}

Returns memories ranked by a composite score combining semantic similarity, heat, keyword overlap, temporal proximity, and namespace ownership.

Scoring formula:

base_score = (1 - cosine_distance) * similarity_weight + heat * heat_weight
fused_score = base_score * (1 + keyword_weight * keyword_overlap)
                        * (1 + temporal_boost)
                        * (1 + namespace_boost)    // if namespace matches

Scoring enhancements (v2.6.0):

• Keyword overlap — exact word matches between query and memory content boost the score. Helps with proper nouns, project names, and technical terms. Weight: recall.keyword_weight (default: 0.15).
• Temporal proximity — queries containing time references ("yesterday", "last week", "last month", dates) boost memories from the matching time window. Configurable: recall.temporal_max_boost (0.4), recall.temporal_decay_days (7.0).
• Namespace ownership — memories from the querying agent's own namespace get a small boost in multi-agent setups. Weight: recall.namespace_boost (default: 0.1).

Hot Context

POST /api/v1/agent/hot-context

{
  "limit": 10,
  "namespace": "my-agent",
  "memory_type": "fact"
}

Returns the top memories without a search query — the "always on" context layer. Useful for injecting baseline context before any user interaction.

Memories are sorted by: pinned first → highest heat → most recently updated.

This is designed for the L0/L1 context pattern: load a small, high-value context packet (~100-500 tokens) on every turn without running a search query. The agent always knows its most important memories before the user says anything.

Cold Storage Search

Use tier: "cold" on the semantic search endpoint to query archived memories:

{
  "query": "Stripe webhook configuration",
  "tier": "cold",
  "limit": 5
}

Cold storage combines pgvector similarity search with AGE graph entity traversal. Results from graph traversal are marked with "source": "graph_traversal" and deduped by node ID. Archived memories are the static importance layer — permanently valuable facts that have settled into a stable state. They don't decay further because their importance is established.

Graph Visualization

Get Memory Graph

GET /api/v1/admin/visualize/graph?limit=200&namespace=daedalus

Returns { nodes, links, total_nodes } — edges are filtered to only include edges between returned nodes.

Thermodynamic Config

Get Config

GET /api/v1/settings/thermo

Update Config

PATCH /api/v1/settings/thermo

Configure half-lives, decay classes, resonance spread, active index limits, recall scoring, and consolidation settings per tenant.

Recall scoring fields (v2.6.0):

Feedback

Memory Feedback

POST /api/v1/feedback

{
  "node_id": "uuid-here",
  "signal": "relevant"
}

Signals: relevant (boosts heat + stability), outdated (deprioritizes), wrong (flags for review).

Analytics

Recall Analytics

GET /api/v1/admin/recall-analytics

Returns recall patterns, hit rates, and tuning suggestions.

Dashboard Stats

GET /api/v1/admin/dashboard

Returns node counts, heat distribution, type distribution, namespace breakdown, and recent activity.

Usage

GET /api/v1/admin/usage

Returns sync requests, nodes added, and latency metrics for the current billing period.

Triggers

Triggers are reactive rules that fire when memory events occur. See the Triggers Guide for full documentation.

List Triggers

GET /api/v1/triggers

Returns all triggers for the authenticated tenant.

Create Trigger

POST /api/v1/triggers

Update Trigger

PATCH /api/v1/triggers/:id

Supports partial updates: enabled, name, action_config.

Delete Trigger

DELETE /api/v1/triggers/:id

Returns 204 No Content on success.

Trigger History

GET /api/v1/triggers/history?limit=50

Returns recent trigger firings with event, action, node, and result details.

Events

Actions

Rate Limits

Rate-limited responses return 429 Too Many Requests with a Retry-After header.