HTTP API

The Cordis plugin registers HTTP endpoints on the DSH web server when the webServer service is present. These endpoints are the integration surface for external tools and the web panel.

Base Path

All endpoints are served under /evo/. The pre-rename path /evo-memory/ is still mounted as an alias for backward compatibility.

The web server binds to loopback by default. All responses are JSON.

Endpoints

GET /evo/status

Returns service status.

Response:

{
  "ok": true,
  "databasePath": "~/Library/Application Support/evo/memory.db",
  "busy": false
}

Field	Type	Description
ok	boolean	Service is operational
databasePath	string	Path to SQLite database
busy	boolean	Reflection or consolidation in progress

GET /evo/memories

Lists memory items with optional filtering.

Query Parameters:

Parameter	Type	Description
scopeType	string	Filter by scope type: global, project, etc.
scopeId	string	Filter by scope identifier
scopeKey	string	Combined scope filter
kind	string	Comma-separated list of kinds: fact,constraint
text	string	Full-text search
tags	string	Tag filter
limit	number	Maximum items to return

Response:

{
  "items": [
    {
      "id": "abc123",
      "scope": { "type": "project", "id": "~/projects/myapp" },
      "kind": "fact",
      "title": "Database uses PostgreSQL",
      "content": "The project uses PostgreSQL 15 with...",
      "tags": ["database", "infrastructure"],
      "source": { "session": "sess_xyz", "turn": 5 },
      "createdAt": "2026-08-01T10:00:00Z",
      "updatedAt": "2026-08-15T14:30:00Z",
      "uses": 12
    }
  ]
}

GET /evo/memories/:id

Returns a single memory item.

Response: Same structure as items in the list, or 404 if not found.

GET /evo/scopes

Returns the scope tree with item counts.

Response:

{
  "scopes": [
    {
      "type": "global",
      "id": null,
      "count": 15
    },
    {
      "type": "project",
      "id": "~/projects/myapp",
      "count": 43
    }
  ]
}

GET /evo/events

Returns recent activity log (reflects, consolidations, imports).

Query Parameters:

Parameter	Type	Description
limit	number	Maximum events to return (newest first)

Response:

{
  "events": [
    {
      "type": "reflect",
      "timestamp": "2026-08-15T14:30:00Z",
      "scope": { "type": "project", "id": "~/projects/myapp" },
      "added": 2,
      "updated": 1,
      "evicted": 0
    }
  ]
}

POST /evo/consolidate

Triggers consolidation for a scope. Consolidation merges related memories, removes duplicates, and enforces capacity limits.

Request Body:

{
  "scope": {
    "type": "project",
    "id": "~/projects/myapp"
  }
}

Response:

{
  "ok": true,
  "before": 45,
  "after": 32,
  "merged": 8,
  "evicted": 5
}

POST /evo/import-workspace

Triggers workspace file import for a directory.

Request Body:

{
  "cwd": "~/projects/myapp",
  "force": false
}

Field	Type	Description
cwd	string	Working directory to import
force	boolean	Re-import even if already imported

Response:

{
  "ok": true,
  "imported": 5,
  "updated": 2,
  "skipped": 1
}

GET /evo/skills

Lists skills with filtering options.

Query Parameters:

Parameter	Type	Description
scopeType	string	Filter by scope type
scopeId	string	Filter by scope identifier
scopeKey	string	Combined scope filter
text	string	Search skill names and bodies
includeDormant	boolean	Include dormant skills
limit	number	Maximum items to return

Response:

{
  "skills": [
    {
      "name": "git-commit-workflow",
      "trigger": "When committing code",
      "path": ".paper/agents/skills/git-commit-workflow",
      "usageCount": 5,
      "dormant": false,
      "promoted": true,
      "scope": { "type": "project", "id": "~/projects/myapp" }
    }
  ]
}

GET /evo/backlog

Returns the replay buffer backlog size for a scope.

Query Parameters:

Parameter	Type	Description
scopeType	string	Required: scope type
scopeId	string	Required for non-global: scope identifier
scopeKey	string	Alternative: combined scope filter

Response:

{
  "replaySize": 7,
  "scope": { "type": "project", "id": "~/projects/myapp" }
}

The replaySize indicates how many distillation batches are queued for the next consolidation. When this grows large (10+), auto-consolidation may trigger.

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "Scope not found",
  "code": "SCOPE_NOT_FOUND"
}

Usage Example

# Check status
curl http://localhost:3000/evo/status

# List project memories
curl "http://localhost:3000/evo/memories?scopeType=project&scopeId=~/projects/myapp"

# Search for constraints
curl "http://localhost:3000/evo/memories?kind=constraint&text=test"

# Trigger consolidation
curl -X POST http://localhost:3000/evo/consolidate \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "project", "id": "~/projects/myapp"}}'