store
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…
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. Relationships must link entities you own; a refused relationship is reported in relationships_refused rather than failing the call.
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 | A path on the SERVER's filesystem, not yours. The file is read by the Neotoma instance, so this only works when your client runs on the same machine as the instance — the axis is co-located vs remote, not desktop vs web. Against a hosted or otherwise remote instance it cannot see your disk and is rejected with ERR_FILE_PATH_IS_SERVER_LOCAL. To send a file from a remote client: upload the bytes (POST /sources/upload, multipart/form-data) and pass the returned source_id, or inline small files with file_content (base64) + mime_type. MIME type is auto-detected from the content or extension when not provided. | |
| 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. | |
| expected_entity_absent | No | When true, atomically create exactly one structured entity only if its complete schema-declared physical identity is absent. Requires commit=true and a nonempty idempotency_key; file, relationship, interpretation, intake, target and sync combinations are refused. Omitted or false preserves ordinary upsert behavior. Exact retries return the original immutable operation receipt without new effects. |