store
Persist structured entities, raw files, or both together with provenance, deduplication, and relationship support.
Instructions
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 bytes create a content-addressed sources row (SHA-256 dedup per user); the response includes source_id / content_hash for the unstructured leg. The server does not invent structured fields from opaque blobs without an explicit interpretation block or a separate interpretation flow. Agents should parse and extract entities first when they need structured data from a readable 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| commit | No | When false, runs in plan/dry-run mode: resolves entities and returns planned actions ("would_create" / "would_match_existing") without persisting observations or source rows. Useful for previewing a structured store before committing. | |
| strict | No | When true, refuse silent merges: only match an existing entity when the entity's schema declares canonical_name_fields that the request matches, or when target_id is supplied. Prevents accidental coalescing into a pre-existing record. | |
| user_id | No | ||
| entities | No | ||
| file_path | No | Local file path (alternative to file_content). If provided, file will be read from filesystem. MIME type will be auto-detected from extension if not provided. Works in local environments (Cursor, Claude Code) where MCP server has filesystem access. Does NOT work in web-based environments (claude.ai, chatgpt.com) - use file_content for those. | |
| mime_type | No | MIME type (e.g., 'application/pdf', 'text/csv') - required with file_content, optional with file_path (auto-detected from extension) | |
| file_content | No | Base64-encoded file content. Use file_path for local files instead of base64 encoding. | |
| relationships | No | Optional. Create relationships between entities in this request. Use `source_index` or `target_index` for entities in this request, and `source_entity_id` or `target_entity_id` for existing entities. Index and id endpoints may be mixed in one relationship. | |
| external_actor | No | Upstream artifact author (e.g. GitHub user) stamped into observation provenance alongside AAuth agent attribution. Matches `ExternalActorInputSchema` in `action_schemas.ts`. | |
| interpretation | No | Optional interpretation provenance for source-derived structured extraction. Supplying this creates an interpretation row and links new observations to it. Omit for ordinary already-structured/chat-native facts, which keep observations.interpretation_id NULL. | |
| source_peer_id | No | Optional Neotoma peer id to stamp on observations for cross-instance sync loop prevention (Phase 5). Requires `observation_source: sync` in practice. | |
| source_storage | No | Storage mode for file ingestion. Default 'inline' copies bytes into the database (portable, durable). 'reference' stores only a path + metadata row without copying bytes — zero DB bloat, but host-local and depends on the file staying in place. Requires file_path (not file_content). Derivations (observations/entities) are still materialized at ingest. Use 'reference' for large local files you control; use 'inline' for anything that must be shared or portable. | |
| idempotency_key | No | Required for structured path, optional for unstructured-only path. | |
| source_priority | No | Trust/priority of this observation's source. Only affects snapshot resolution for fields whose merge strategy is highest_priority (set via register_schema reducer_config); under the default last_write strategy it is stored but ignored. | |
| original_filename | No | Original filename or source label (optional). For unstructured: auto-detected from file_path if not provided. For structured (entities): omit when data is agent-provided (no file origin); the source will have no filename. Pass only when mirroring a real file name or when a display label is desired. | |
| observation_source | No | Classifies the *kind* of write being performed, orthogonal to `source_priority`. See `Observation.observation_source` for the full semantic contract. Defaults to `llm_summary` when unspecified. Applies to every observation created by this request. | |
| file_idempotency_key | No | Optional idempotency key for file path when sending structured + unstructured in one call. |