MCP

Connect your agent.

Use a client that supports Streamable HTTP to read and propose changes in your ConceptMem database.

1. Get the connection details

Create a workspace key in the console and copy the MCP endpoint from Connections. Use the endpoint exactly as displayed for your database.

Example MCP client configuration

{
  "mcpServers": {
    "conceptmem": {
      "url": "YOUR_WORKSPACE_MCP_ENDPOINT",
      "headers": {
        "Authorization": "Bearer YOUR_WORKSPACE_KEY"
      }
    }
  }
}

This is a common client configuration format; your client may expose the same URL and authorization fields through its settings. Keep keys private and revoke a key from the console if it is exposed.

2. Read the vocabulary

Call ontology_list before writing. Reuse class and predicate names. The following example starts in a fresh database; an existing schema or policy may change its results.

ontology_list arguments

{}

3. Propose a value, then update it

Call memory_insert with the first observation:

memory_insert — first observation

{
  "entityType": "customer",
  "entityRef": "customer:crm_1042",
  "data": { "contact_channel": "phone" },
  "source": "support",
  "confidence": 0.97,
  "extractionMethod": "structured_import",
  "idempotencyKey": "quickstart-crm-1042-phone-1"
}

Send a second observation with the same entity reference, changing contact_channel to email and using a new idempotency key. Under the fresh database’s default policy, email becomes current and phone remains in history. Structured input does not require hosted text extraction.

The service records the authenticated actor and the mutation timestamp. Supply an identifiable source and an extraction method, and use confidence between zero and one.

4. Inspect the result

Default memory_insert response
Field	What to inspect
`ok`	Whether processing completed. It does not mean every proposed field was accepted.
`results[].operationDetails`	Applied changes, including their available fact, relation and provenance details.
`results[].skippedDetails`	Fields deliberately not written and the reason for each skip.
`results[].violationDetails`	Warnings and refusals. A blocking finding refused the associated change.
`results[].pendingReviews`	Proposals awaiting a review decision.
`operation`	The write operation reference and its completion or recovery status.

For profile: "compact-v1", inspect the receipt’s operations, skipped, violations and pendingReview. Response profiles have different shapes; parse the profile your client requested.

5. Read current state and history

memory_get arguments

{ "entity": "customer:crm_1042" }

memory_history arguments

{ "entity": "customer:crm_1042", "limit": 20 }

The current record should contain email. History should show the change from phone to email and its recorded provenance. Entity history uses no profile; evidence by fact or relation IDs uses a profile and a different set of arguments.

Recover an interrupted insertion

Give each logical insertion a unique idempotencyKey. After a lost response, query memory_operation with that key using the same authenticated principal. Reuse the key only for identical input.

memory_operation arguments

{ "idempotencyKey": "quickstart-crm-1042-phone-1" }

If an operation is ready to resume, call memory_insert with its returned operationId only, plus an optional response profile. Inspect confirmed results and failure information before proceeding.

Tools at a glance

Your client can discover the complete argument and output schemas from the connected endpoint. This reference covers the current service contract; deployed versions may differ during pre-release validation.

MCP tool reference
Tool	Purpose and inputs
`memory_insert`	Submit an observation (proposal). entityType, entityRef, data, source, confidence; optional relations and idempotencyKey. Use text for hosted extraction, or operationId alone to resume.
`memory_operation`	Recover the result of an interrupted insertion. Exactly one of operationId or idempotencyKey.
`memory_search`	Text search over current state. query; optional entityType, limit and profile. Continue with the returned cursor or nextOffset for that response format.
`memory_get`	Load an entity’s current view. Exactly one of entity or entities (up to 20). Optional predicates, asOf and profile.
`memory_history`	Changelog for an entity. entity, limit and offset for change history. For evidence, use profile with exactly one of factIds or relationIds instead.
`memory_traverse`	Walk typed relations. entity; optional relation, direction, depth, limit and cursor.
`memory_validate`	Check a structured observation without writing. entityType, data; optional entityRef, relations, source and confidence.
`ontology_preview`	Preview a proposed schema definition. class; optional predicates, relationTypes, strict, defaultPolicy and expectedRevision.
`ontology_define`	Propose class, predicate, or relation definitions. The same definition fields as ontology_preview; schema writes depend on your authority and the database mode.
`ontology_list`	Read the schema that gates writes. Optional profile, classes and cursor. Read the vocabulary before proposing new names.
`memory_export`	Projection of current state — not a write surface. Optional format, entities, entityTypes, predicates, limit and cursor.
`memory_retract`	Retract a current fact. entity and predicate; optional typed value, source, reason and confidence.
`memory_review`	Approve or reject a held proposal. action: list, approve or reject. Decisions require reviewId; listings support limit and offset.

Validation and schema changes

memory_validate checks a proposed structured observation without writing. It can report violations and predicted refusals; a successful validation does not guarantee a later write or reserve that state.

ontology_preview lets you inspect a schema proposal. Use the revision returned by ontology_list as expectedRevision when applying a definition. Workspace keys remain agent credentials; human schema administration uses authenticated console access.

Pagination and incomplete responses

Inspect page and coverage information. Follow the returned continuation with the same filters. Some responses use cursors; default search and entity history use offsets. A truncated response is not a complete record or export. An export is a view of your data, not a full restorable backup.

← Documentation Understand the public types →