MCP

Connect your agent.

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

New to ConceptMem? Start with the account-to-first-record walkthrough. This guide covers authentication and the tool calls behind those conversations.

1. Choose your authentication method

Open your database’s Connections page and copy its MCP endpoint exactly as displayed. Connect using OAuth or a workspace API key, depending on your client.

OAuth: authorize through your account

Add the endpoint as a remote MCP server in a client that supports OAuth.
Start authentication and sign in to ConceptMem in the browser.
Review the application and select the database. Choose Read and write to follow the write examples below, if your database role permits it.
Allow access, return to the client, and enable the connection.

You do not need to generate an API key for this path. Manage the application’s access in the database’s Settings. Database rules still govern its proposals, including any changes to the ontology.

API key: configure a database credential

Create an API key from Connections, or use an existing key for this database. Save a newly generated secret before leaving the page; it cannot be retrieved later. Use the client configuration provided by Connections, or adapt this example to your client’s format.

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.

Use the returned entity identity. Save results[].canonicalId or results[].entityId (the UUID) after memory_insert. Use that value for memory_get, memory_history, memory_traverse, and memory_retract. A raw input entityRef can normalize differently; a NOT_FOUND result does not by itself mean the write failed.

Inserted edges use relationType and targetRef. On memory_get, omit relations or pass false or an object selector; boolean true is invalid.

For schema setup, complete payloads, and expected outcomes, follow the write, read, and history tutorial.

5. Read current state and history

memory_get arguments

{ "entity": "CANONICAL_ID_FROM_RECEIPT" }

memory_history arguments

{ "entity": "CANONICAL_ID_FROM_RECEIPT", "limit": 20 }

Replace the placeholder with the receipt’s canonicalId or entity UUID. 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`	Propose updates with their provenance. entityType, entityRef, data, source, confidence; optional relations and idempotencyKey. Use text for hosted extraction, or operationId alone to resume.
`memory_operation`	Recover confirmed receipts from a write plan. Exactly one of operationId or idempotencyKey.
`memory_search`	Find current records by text. query; optional entityType, limit and profile. Continue with the returned cursor or nextOffset for that response format.
`memory_get`	Read an entity’s current facts and relationships. Exactly one of entity or entities (up to 20). Optional predicates, asOf and profile.
`memory_history`	Inspect an entity’s change history. entity, limit and offset for change history. For evidence, use profile with exactly one of factIds or relationIds instead.
`memory_traverse`	Follow typed relationships between entities. entity; optional relation, direction, depth, limit and cursor.
`memory_validate`	Check a proposed update before writing. entityType, data; optional entityRef, relations, source and confidence.
`ontology_preview`	Check a proposed schema change before applying it. class; optional predicates, relationTypes, strict, defaultPolicy and expectedRevision.
`ontology_define`	Propose entity types, fields, and relationship definitions. The same definition fields as ontology_preview; schema writes depend on your authority and the database mode.
`ontology_list`	Read the shared vocabulary and its constraints. Optional profile, classes and cursor. Read the vocabulary before proposing new names.
`memory_export`	Export a derived view of current records. Optional format, entities, entityTypes, predicates, limit and cursor.
`memory_retract`	Retract a current fact or relationship. entity and predicate; optional typed value, source, reason and confidence.
`memory_review`	Approve or reject a proposal held for review. 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 →