Neotoma

Retrieve a signed URL for accessing a file

Retrieve the current snapshot of an entity with provenance information. Supports historical snapshots via 'at' parameter.

List all observations for a given entity

Retrieve the provenance chain for a specific field in an entity snapshot

Create a typed relationship between two entities. relationship_type: PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, or EMBEDS. Use EMBEDS when a container entity (e.g. blog post, document) embeds an asset entity (e.g. image, attachment): source_entity_id = container, target_entity_id = asset. For images/files stored in Neotoma: store the file via store (get source_id), create an image/media entity with source_id, then create_relationship(EMBEDS, post_entity_id, image_entity_id). Optional metadata: caption, order.

List relationships for an entity

Get the current snapshot of a specific relationship with provenance

Use this when you need filtered entity lists (by type, pagination, and optional published/date filters) or lexical/semantic retrieval via search. Strict mode: search cannot be combined with non-default sorting or published filters. Set include_snapshots=false for lightweight responses that omit snapshot/provenance/raw_fragments. Compatibility aliases search_query and query are accepted but search is canonical.

Query timeline events with filters (type, date range, source). Returns chronological events derived from date fields in sources.

Retrieve entity by identifier (name, email, etc.) across entity types or specific type. Falls back to semantic search when keyword match returns no results.

Retrieve entities connected to a given entity via relationships. Supports n-hop traversal.

Retrieve complete graph neighborhood around a node (entity or source): related entities, relationships, sources, and events.

Unified storing for structured, file-backed, or combined payloads in one request. Choose path by source: file- or resource-sourced (attachment/file to preserve) → use file_content+mime_type or file_path; conversation- or tool-sourced (chat or other MCP) → use entities. You may send both entities and file input in the same call. File inputs are stored raw with content-addressed SHA-256 deduplication; the server does not perform AI interpretation during store. Agents should parse and extract entities first when they need structured data from a file, then send those entities alongside the raw file. IMPORTANT FOR STRUCTURED DATA: Include ALL fields from source data. Schema fields go to observations; non-schema fields go to raw_fragments for future schema expansion.

Store structured entities only. Use for conversation- or tool-sourced data (e.g. from chat or another MCP). In chat: one call per turn with entities [conversation, agent_message], idempotency_key (per-store unique, e.g. conversation-{conversation_id}-{turn_id}-{timestamp_ms}), stable turn identity in agent_message (e.g. turn_key or id = conversation_id:turn_id), and relationships: [{ relationship_type: PART_OF, source_index: 1, target_index: 0 }]. Overwriting between branches is OK; history via list_observations. Use when you already have entity objects and do not need file ingestion.

Store raw files only. Use when data is file- or resource-sourced (user attachment or file to preserve). Provide file_content (base64) + mime_type or file_path.

Parse local or base64-encoded files into agent-readable text and first-page PDF images without storing anything. Use before store when you need to extract entities from a file.

Create high-priority correction observation to override AI-extracted fields. Corrections always win in snapshot computation.

Merge duplicate entities. Rewrites observations from source entity to target entity and marks source as merged.

Delete an entity. Creates a deletion observation so the entity is excluded from snapshots and queries. Immutable and reversible for audit; use for user-initiated or GDPR-style removal from active use.

Delete a relationship. Creates a deletion observation so the relationship is excluded from snapshots and queries. Immutable and reversible for audit.

Restore a deleted entity. Creates a restoration observation (priority 1001) that overrides the deletion. Entity becomes visible in snapshots and queries again. Immutable restoration for audit.

Restore a deleted relationship. Creates a restoration observation (priority 1001) that overrides the deletion. Relationship becomes visible in snapshots and queries again. Immutable restoration for audit.

Return canonical entity counts by entity_type for the authenticated user. Uses the same dashboard stats aggregation behind GET /stats and sorts results by count descending, then entity_type ascending. Use this when the user asks for counts by type, histograms, or sorted totals. This returns row counts, unlike list_entity_types where field_count is schema field width.

List available entity types. Without keyword: returns a short summary (entity_type, schema_version, field_count) for all types. field_count here means schema field width, not stored entity row count. With keyword: returns full schema (field_names, field_summary) for matching types; pass summary: true to get summary only. Uses hybrid search when keyword is provided: keyword matching first, then vector semantic search. Use before storing structured data to determine the correct entity_type.

Analyze raw_fragments to identify fields that should be promoted to schema fields. Returns recommendations with confidence scores based on frequency and type consistency.

Get schema update recommendations for an entity type from raw_fragments analysis, agent suggestions, or inference.

Incrementally update a schema by adding new fields from raw_fragments or agent recommendations. Creates new schema version and activates it immediately, so all new data stored after this call will use the updated schema. Optionally migrates existing raw_fragments to observations for historical data backfill.

Register a new schema or schema version. Supports both global and user-specific schemas.

Get the authenticated user ID for the current MCP session. Returns the user_id that is automatically used for all authenticated actions.

Check for stale entity snapshots (snapshots with observation_count=0 but observations exist). Returns health status and count of stale snapshots.

Check if a newer npm version is available. Returns updateAvailable, message, and suggestedCommand. Call at session start to encourage user to upgrade.