Agent Evolution

The Agent Evolution API reports trajectories that consumed a specific Experience and their outcome distribution. These operations are currently available through HTTP only.

API Reference

List Experience application trajectories

Return a paginated list of trajectories that successfully read the specified Experience. The query is restricted to Experiences and trajectories owned by the current user.

Code Entry Points:

• openviking/server/routers/agent_evolution.py:list_experience_trajectories - HTTP route
• openviking/service/agent_evolution_service.py:AgentEvolutionService.list_trajectories_by_experience - Core implementation

Parameters

HTTP API

GET /api/v1/agent-evolution/experiences/trajectories?experience_uri={experience_uri}&limit=50&offset=0

curl -X GET "http://localhost:1933/api/v1/agent-evolution/experiences/trajectories?experience_uri=viking://user/default/memories/experiences/exchange.md&limit=50&offset=0" \
  -H "X-API-Key: your-key"

Response Example

{
  "status": "ok",
  "result": {
    "experience_uri": "viking://user/default/memories/experiences/exchange.md",
    "items": [
      {
        "uri": "viking://user/default/memories/trajectories/exchange_20260805020000.md",
        "name": "exchange_20260805020000.md",
        "description": "Handle an exchange request",
        "created_at": "2026-08-05T02:00:00Z",
        "updated_at": "2026-08-05T02:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "time": 0.01
}

Each item contains only the indexed fields that are present among uri, name, description, created_at, and updated_at.

Get Experience outcome distribution

Count trajectories that consumed the specified Experience across the five supported outcomes. The query uses exact scalar-tag aggregation and does not load every trajectory file.

Code Entry Points:

• openviking/server/routers/agent_evolution.py:get_experience_outcome_distribution - HTTP route
• openviking/service/agent_evolution_service.py:AgentEvolutionService.get_experience_outcome_distribution - Core implementation

Parameters

HTTP API

GET /api/v1/agent-evolution/experiences/outcomes?experience_uri={experience_uri}

curl -X GET "http://localhost:1933/api/v1/agent-evolution/experiences/outcomes?experience_uri=viking://user/default/memories/experiences/exchange.md" \
  -H "X-API-Key: your-key"

Response Example

{
  "status": "ok",
  "result": {
    "experience_uri": "viking://user/default/memories/experiences/exchange.md",
    "outcome_distribution": [
      {"outcome": "success", "count": 4},
      {"outcome": "failure", "count": 1},
      {"outcome": "partial", "count": 0},
      {"outcome": "unknown", "count": 0},
      {"outcome": "unfinished", "count": 0}
    ]
  },
  "time": 0.01
}

The response always includes success, failure, partial, unknown, and unfinished. Trajectories created by older versions and not yet re-indexed do not carry outcome tags and are therefore excluded.

Related Documentation

• Sessions - Commit sessions and generate Agent Evolution memories
• Memory - Read and recall memories