Data model

MongoDB is the source of truth and the dynamic configuration store. Agents, skills, memory, and runs are documents whose shapes evolve — which is exactly why a document database fits.

Collections

agents              agent_blueprints   skills
agent_skill_links   memories           goals
tasks               agent_runs         tool_permissions
board_items         board_links        telegram_commands
projects            events             artifacts
approvals           integrations

Collection	Holds
`agents`	Agent definitions (config + policy + permissions).
`agent_blueprints`	Templates agents are instantiated from.
`skills`	Reusable, versioned skills.
`agent_skill_links`	Many-to-many agent ↔ skill assignments (with pinned versions).
`memories`	Scoped memory entries, including `pending` ones in the review queue.
`goals`	High-level objectives decomposed into tasks.
`tasks`	Units of work with a status lifecycle.
`agent_runs`	One document per execution; status, logs ref, events, result.
`tool_permissions`	Tool/permission catalog and per-agent grants.
`board_items`	Internal board items (authoritative).
`board_links`	Mapping internal items ↔ external (Plane) work items.
`telegram_commands`	Audit of inbound commands + allowlist.
`projects`	Project records and per-project config.
`events`	Event log (mirrors NATS subjects for durability/inspection).
`artifacts`	Outputs produced by runs (diffs, PR links, files).
`approvals`	Pending and resolved human-approval requests.
`integrations`	External system credentials/config (Plane, registries).

agents

See Concepts → Agents for the full document. Key indexes: slug (unique), status, skills.

skills

See Concepts → Skills. Key indexes: slug

version (unique), tags, status.

memories

See Concepts → Memory. Key indexes: scope + project_id, agent_id, tags, text index on title + content, and status (to surface the pending review queue).

tasks

{
  "_id": "task_456",
  "goal_id": "goal_123",
  "project_id": "nexus",
  "title": "Implement login endpoint",
  "description": "...",
  "status": "ready_for_agent",
  "assigned_agent_id": "agent_backend_implementer",
  "lease": { "run_id": null, "expires_at": null },
  "depends_on": ["task_455"],
  "created_at": "2026-05-30T00:00:00Z",
  "updated_at": "2026-05-30T00:00:00Z"
}

agent_runs

{
  "_id": "run_123",
  "agent_id": "agent_backend_implementer",
  "task_id": "task_456",
  "status": "running",
  "k8s_job": "nexus-run-run_123",
  "started_at": "2026-05-30T00:00:00Z",
  "finished_at": null,
  "result": null,
  "logs_ref": "artifacts/run_123/logs",
  "events": ["AgentRunStarted"]
}

Notes

Use change streams later for live UI updates and reconciliation.
Transactions only where genuinely needed (e.g. task lease + run create).
Indexes are defined and managed by the nexus-db crate.

Collections​

agents​

skills​

memories​

tasks​

agent_runs​

Notes​

Related​