Neotoma

Contacts

People, companies, roles, and the relationships between them. Contacts are a common entity type in Neotoma - they anchor relationships, tasks, transactions, and decisions to real-world identities.

Store#

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

MCP

store_structured({ entities: [ { entity_type: "contact", name: "Sarah Chen", email: "sarah@example.com", company: "Acme Corp", role: "VP Engineering", relationship: "client" } ], idempotency_key: "contact-sarah-chen-1710268800" })

CLI

neotoma store --json='[{ "entity_type": "contact", "name": "Sarah Chen", "email": "sarah@example.com", "company": "Acme Corp", "role": "VP Engineering", "relationship": "client" }]'

REST API

curl -X POST http://localhost:3080/api/store \ -H "Content-Type: application/json" \ -d '{ "entities": [{ "entity_type": "contact", "name": "Sarah Chen", "email": "sarah@example.com", "company": "Acme Corp", "role": "VP Engineering", "relationship": "client" }] }'

Common fields for contact:

FieldExample
name"Sarah Chen"
email"sarah@example.com"
company"Acme Corp"
role"VP Engineering"
relationship"client"

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

Retrieve#

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

CLI

# List all contacts neotoma entities list --type contact # Search by name or identifier neotoma entities search --query "Sarah Chen" --type contact # Inspect full history for one contact neotoma observations list --entity-id <entity_id> # See related entities (tasks, transactions, etc.) neotoma relationships list --entity-id <entity_id>

MCP

// Find by identifier retrieve_entity_by_identifier({ identifier: "Sarah Chen", entity_type: "contact" }) // List contacts with filters retrieve_entities({ entity_type: "contact", limit: 20 }) // Expand relationships retrieve_related_entities({ entity_id: "<entity_id>", relationship_types: ["REFERS_TO", "PART_OF"] })

What your agent can answer#

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

  • “Who did I last meet with at Acme Corp?”
  • “Show all contacts linked to the Q4 proposal”
  • “What changed about Sarah's record since January?”

What Neotoma guarantees#

Every contact 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#