Neotoma

Decisions

Choices, rationale, and the audit trail that proves why. Decisions in Neotoma link to the inputs and context that produced them - so when the same question comes up later, you can trace the original reasoning.

Store#

Store a decision with any fields that describe it. Neotoma auto-discovers the schema from the first observation - no migration required.

MCP

store_structured({ entities: [ { entity_type: "decision", title: "Use PostgreSQL for the data layer", status: "accepted", rationale: "Need JSONB, row-level security, mature tooling", decided_by: "agent:cursor-session-0a3f", alternatives_considered: ["SQLite", "DynamoDB"], decided_at: "2026-03-15T14:30:00Z" } ], idempotency_key: "decision-pg-datastore-1710268800" })

CLI

neotoma store --json='[{ "entity_type": "decision", "title": "Use PostgreSQL for the data layer", "status": "accepted", "rationale": "Need JSONB, row-level security, mature tooling", "decided_by": "agent:cursor-session-0a3f", "alternatives_considered": ["SQLite", "DynamoDB"], "decided_at": "2026-03-15T14:30:00Z" }]'

REST API

curl -X POST http://localhost:3080/api/store \ -H "Content-Type: application/json" \ -d '{ "entities": [{ "entity_type": "decision", "title": "Use PostgreSQL for the data layer", "status": "accepted", "rationale": "Need JSONB, row-level security, mature tooling", "decided_by": "agent:cursor-session-0a3f", "alternatives_considered": ["SQLite", "DynamoDB"], "decided_at": "2026-03-15T14:30:00Z" }] }'

Common fields for decision:

FieldExample
title"Use PostgreSQL for the data layer"
status"accepted"
rationale"Need JSONB, row-level security, mature tooling"
decided_by"agent:cursor-session-0a3f"
alternatives_considered["SQLite", "DynamoDB"]

Fields are flexible - add any property your workflow needs. The schema evolves automatically via progressive schema enforcement.

Retrieve#

Query decisions by type, search by keyword, inspect version history, and traverse relationships.

CLI

# List all decisions neotoma entities list --type decision # Search by title or keyword neotoma entities search --query "PostgreSQL" --type decision # Full provenance: who decided, when, and what changed neotoma observations list --entity-id <entity_id> # See what entities influenced this decision neotoma relationships list --entity-id <entity_id>

MCP

// Find by title retrieve_entity_by_identifier({ identifier: "Use PostgreSQL for the data layer", entity_type: "decision" }) // List recent decisions retrieve_entities({ entity_type: "decision", limit: 20 }) // Trace provenance list_observations({ entity_id: "<entity_id>" })

What your agent can answer#

With decisions stored in Neotoma, your agent can answer questions like:

  • “Why did we choose PostgreSQL over SQLite?”
  • “What decisions were made in the last sprint?”
  • “Show the full rationale chain for the API design decision”

What Neotoma guarantees#

Every decision stored in Neotoma gets the same set of integrity guarantees:

  • Versioned history - Every change creates a new version. Previous states are always accessible.
  • Deterministic state - Same observations always produce the same entity snapshot.
  • Auditable provenance - Every field traces back to the observation that set it.
  • Schema validation - Fields conform to the discovered or defined schema.

See all memory guarantees compared across memory models.

Next steps#