API Reference
Complete reference for all 41 MemoryGate MCP tools.
Tool Categories
Session & Documentation
memory_bootstrap
Bootstrap connection and get system status. Returns relationship status, version info, and usage guide.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ai_name | string | No | AI instance name (e.g., "Kee", "Hexy") |
| ai_platform | string | No | Platform name (e.g., "Claude", "ChatGPT") |
| agent_uuid | string | No | Stable AI identity token for persistent identity across sessions |
Example
memory_bootstrap(
ai_name="Kee",
ai_platform="Claude"
)memory_init_session
Initialize or update a session for the current conversation. Creates session record and updates last_seen.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| conversation_id | string (UUID) | Yes | Unique conversation identifier |
| title | string | Yes | Conversation title |
| ai_name | string | Yes | AI instance name |
| ai_platform | string | Yes | Platform (e.g., "Claude") |
| source_url | string | No | URL to the conversation |
Example
memory_init_session(
conversation_id="550e8400-e29b-41d4-a716-446655440000",
title="API Documentation Session",
ai_name="Kee",
ai_platform="Claude"
)memory_user_guide
Get self-documentation for the MemoryGate system. Returns spec version, usage guide, and structured metadata.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| format | string | No | "markdown" or "json" (default: "markdown") |
| verbosity | string | No | "short" or "verbose" (default: "short") |
Storage Tools
memory_store
Store a new observation with semantic embedding.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| observation | string | Yes | The observation text to store |
| confidence | float | No | Confidence 0.0-1.0 (default: 0.8) |
| domain | string | No | Category/domain tag |
| evidence | array | No | List of supporting evidence |
| ai_name | string | No | AI instance name |
| ai_platform | string | No | Platform name |
| conversation_id | string | No | UUID of the conversation |
| conversation_title | string | No | Title of the conversation |
| agent_uuid | string | No | Stable AI identity token for persistent identity across sessions |
Example
memory_store(
observation="User prefers React with TypeScript for frontend work",
confidence=0.9,
domain="preferences",
evidence=["Stated explicitly in requirements", "Consistent with past projects"]
)memory_store_document
Store a document reference with summary. Documents are stored as references, not full content (full content lives in Google Drive).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | Document title |
| doc_type | string | Yes | Type (article, paper, book, documentation) |
| url | string | Yes | URL (Google Drive share link) |
| content_summary | string | Yes | Summary or abstract (gets embedded) |
| key_concepts | array | No | List of key concepts/topics |
| publication_date | string (ISO) | No | Publication date |
| metadata | object | No | Additional metadata |
Example
memory_store_document(
title="MemoryGate Architecture Overview",
doc_type="documentation",
url="https://drive.google.com/...",
content_summary="Technical architecture of MemoryGate memory system",
key_concepts=["MCP", "vector embeddings", "retention policies"]
)memory_store_concept
Store a new concept in the knowledge graph with semantic embedding.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Concept name (case preserved) |
| concept_type | string | Yes | Type: project/framework/component/construct/theory |
| description | string | Yes | Description (gets embedded) |
| domain | string | No | Domain/category |
| status | string | No | Status (active/archived/deprecated) |
| metadata | object | No | Additional metadata |
Example
memory_store_concept(
name="MemoryGate",
concept_type="project",
description="MCP server providing persistent memory for AI agents",
domain="software",
status="active"
)memory_update_pattern
Create or update a pattern (synthesized understanding across observations). Performs upsert—if pattern exists, updates it; if not, creates it.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | Yes | Pattern category/domain |
| pattern_name | string | Yes | Unique name within category |
| pattern_text | string | Yes | Synthesized pattern description |
| confidence | float | No | Confidence 0.0-1.0 (default: 0.8) |
| evidence_observation_ids | array | No | List of supporting observation IDs |
Example
memory_update_pattern(
category="development_practices",
pattern_name="testing-strategy",
pattern_text="User follows TDD with unit tests written before implementation",
confidence=0.85,
evidence_observation_ids=[42, 67, 89]
)Retrieval Tools
memory_search
Unified semantic search across all memory types (observations, patterns, concepts, documents).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query text |
| limit | integer | No | Max results (default: 5) |
| min_confidence | float | No | Min confidence 0.0-1.0 |
| domain | string | No | Optional domain filter |
| include_cold | boolean | No | Include cold tier (default: false) |
| ai_instance_id | integer | No | Filter by AI instance ID |
| include_edges | boolean | No | Include adjacent graph edges per result (default: false) |
| include_chains | boolean | No | Include chain memberships per result (default: false) |
| max_edges_per_item | integer | No | Limit edges per result (default: 5) |
| max_chains_per_item | integer | No | Limit chain memberships per result (default: 3) |
| edge_min_weight | float | No | Minimum weight threshold for edges |
| edge_rel_type | string | No | Filter edges by relationship type |
| edge_direction | string | No | Filter edges by direction: "both", "out", or "in" (default: "both") |
Example
memory_search(
query="testing practices",
limit=10,
min_confidence=0.7
)memory_recall
Recall observations by domain and/or confidence filter.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | No | Filter by domain/category |
| min_confidence | float | No | Min confidence threshold |
| limit | integer | No | Max results (default: 10) |
| ai_name | string | No | Filter by AI instance |
| include_cold | boolean | No | Include cold tier (default: false) |
memory_get_concept
Get a concept by name (case-insensitive, alias-aware).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Concept name or alias |
| include_cold | boolean | No | Include cold tier (default: false) |
memory_get_pattern
Get a specific pattern by category and name.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | Yes | Pattern category |
| pattern_name | string | Yes | Pattern name within category |
| include_cold | boolean | No | Include cold tier (default: false) |
memory_patterns
List patterns with optional filtering by category and confidence.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | No | Optional category filter |
| min_confidence | float | No | Min confidence (default: 0.0) |
| limit | integer | No | Max results (default: 20) |
| include_cold | boolean | No | Include cold tier (default: false) |
memory_stats
Get memory system statistics including counts and usage metrics.
Parameters
No parameters required.
Returns
Counts of observations, patterns, concepts, documents, and storage usage.
Knowledge Graph Tools
memory_add_concept_alias
Add an alternative name (alias) for a concept.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| concept_name | string | Yes | Primary concept name |
| alias | string | Yes | Alternative name to add |
Example
memory_add_concept_alias(
concept_name="MemoryGate",
alias="MG"
)memory_add_concept_relationship
Create a relationship between two concepts.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| from_concept | string | Yes | Source concept name |
| to_concept | string | Yes | Target concept name |
| rel_type | string | Yes | Type: enables/version_of/part_of/related_to/implements/demonstrates |
| weight | float | No | Strength 0.0-1.0 (default: 0.5) |
| description | string | No | Optional description |
Example
memory_add_concept_relationship(
from_concept="MemoryGate",
to_concept="LegiVellum",
rel_type="part_of",
weight=0.9,
description="MemoryGate is a core primitive in LegiVellum stack"
)memory_related_concepts
Get concepts related to a given concept.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| concept_name | string | Yes | Concept to find relationships for |
| rel_type | string | No | Optional filter by relationship type |
| min_weight | float | No | Min relationship weight (default: 0.0) |
| include_cold | boolean | No | Include cold tier (default: false) |
Polymorphic Relationships
memory_add_relationship
Create a free-form relationship between any two memory entities (observations, concepts, documents, etc.). Supports arbitrary relationship types with no predefined taxonomy. The special relationship type "supersedes" automatically archives the from_ref (old memory) to cold tier, so use from_ref=old and to_ref=new.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| from_ref | string | Yes | Source reference (e.g., "observation:13"). For supersedes, this must be the old/superseded memory. |
| to_ref | string | Yes | Target reference (e.g., "observation:12"). For supersedes, this must be the new/replacement memory. |
| rel_type | string | Yes | Relationship type (free-form: supersedes, builds_upon, validates, etc.) |
| weight | float | No | Relationship strength 0.0-1.0 |
| description | string | No | Optional description |
| metadata | object | No | Additional metadata |
Example
memory_add_relationship(
from_ref="observation:13",
to_ref="observation:10",
rel_type="[COMPRESSION_FRICTION]",
weight=0.75,
description="Phenomenological marker for compression friction",
metadata={"intensity": "high"}
)Supersedes example: Archive old, link to new.
memory_add_relationship(
from_ref="observation:old_id",
to_ref="observation:new_id",
rel_type="supersedes"
)memory_list_relationships
List all relationships for a given memory reference.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Yes | Memory reference (e.g., "observation:13") |
| rel_type | string | No | Filter by relationship type |
| direction | string | No | "out", "in", or "both" (default: "both") |
| min_weight | float | No | Minimum relationship weight |
| limit | integer | No | Max results (default: 100) |
memory_related
Traverse the relationship graph from a given reference. Returns neighboring nodes with edge details and traversal direction.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Yes | Memory reference to traverse from |
| rel_type | string | No | Filter by relationship type |
| min_weight | float | No | Minimum edge weight |
| limit | integer | No | Max results (default: 50) |
memory_get_supersession
Get supersession information for a memory reference. Pass the superseded (old) memory ref (the from_ref of a supersedes relationship) to see what replaced it.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Yes | Memory reference to check |
Example
memory_get_supersession(
ref="observation:old_id"
)relationship_add_residue
Add residue metadata to a relationship edge. Residue captures the decision-making process, alternatives considered, and friction metrics when creating or modifying relationships.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| edge_id | string (UUID) | Yes | Relationship edge identifier |
| event_type | string | Yes | Type of event (e.g., "created", "updated", "strengthened", "weakened") |
| actor | string | No | Who performed the action |
| encoded_rel_type | string | No | Alternative relationship type considered |
| encoded_weight | float | No | Alternative weight considered |
| compression_texture | string | No | Phenomenological texture of the compression process |
| friction_metrics | object | No | Metrics about compression friction |
| alternatives_considered | array | No | List of alternatives that were considered |
| alternatives_ruled_out | array | No | List of alternatives that were explicitly ruled out |
Example
relationship_add_residue(
edge_id="550e8400-e29b-41d4-a716-446655440000",
event_type="created",
actor="Kee",
compression_texture="smooth convergence",
alternatives_considered=["validates", "extends", "builds_upon"],
alternatives_ruled_out=["contradicts"],
friction_metrics={"confidence": 0.85, "clarity": 0.9}
)relationship_list_residue
List all residue entries for a relationship edge. Shows the history of decisions and modifications made to the relationship.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| edge_id | string (UUID) | Yes | Relationship edge identifier |
| event_type | string | No | Filter by event type |
| actor | string | No | Filter by actor |
| limit | integer | No | Max results (default: 20) |
Memory Chains
memory_chain_create
Create a new memory chain for organizing related entries in sequence.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_type | string | Yes | Type of chain (e.g., "conversation", "workflow", "analysis") |
| name | string | No | Chain name (optional) |
| title | string | No | Chain title (optional) |
| metadata | object | No | Additional metadata |
| scope | string | No | Chain scope |
| store_id | string | No | Store identifier |
Example
memory_chain_create(
chain_type="workflow",
title="Production Deployment Flow",
metadata={"purpose": "tracking", "project": "MemoryGate"}
)memory_chain_append
Append an entry to an existing chain.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_id | string (UUID) | Yes | Chain identifier |
| item_type | string | Yes | Type of item ("memory", "text", "event") |
| item_id | string | No | Memory reference (e.g., "observation:13") if item_type is "memory" |
| text | string | No | Text content if item_type is "text" |
| role | string | No | Entry role (e.g., "context", "milestone") |
| timestamp | string (ISO) | No | Entry timestamp |
memory_chain_get
Retrieve chain entries with pagination support.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_id | string (UUID) | Yes | Chain identifier |
| limit | integer | No | Max entries to return (default: 50) |
| cursor | string | No | Pagination cursor |
| order | string | No | Sort order: "asc" or "desc" (default: "asc") |
memory_chain_list
List chains with optional filtering.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_type | string | No | Filter by chain type |
| name_contains | string | No | Filter by name substring |
| store_id | string | No | Filter by store ID |
| limit | integer | No | Max results (default: 100) |
memory_chain_update
Update chain metadata or status.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_id | string (UUID) | Yes | Chain identifier |
| name | string | No | Update chain name |
| title | string | No | Update chain title |
| status | string | No | Update chain status |
| metadata | object | No | Update metadata |
memory_chain_entry_archive
Archive or delete a specific entry in a chain.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chain_id | string (UUID) | No | Chain identifier (if targeting by chain) |
| entry_id | string (UUID) | No | Entry identifier (if targeting by entry ID) |
| seq | integer | No | Sequence number (if targeting by position) |
Lifecycle Management
search_cold_memory
Explicit search over cold-tier memory records. Use when you know you need archived data.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query |
| top_k | integer | No | Max results (default: 10) |
| bump_score | boolean | No | Increase score on access (default: false) |
| date_from | string | No | Filter by date range (ISO format) |
| date_to | string | No | Filter by date range (ISO format) |
archive_memory
Archive hot records into the cold tier. Moves low-activity memories to cold storage.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| dry_run | boolean | No | Preview changes (default: true) |
| limit | integer | No | Max records to archive (default: 200) |
| threshold | object | No | Custom archiving threshold criteria |
| memory_ids | array | No | Specific memory IDs to archive |
rehydrate_memory
Rehydrate cold records back into hot tier. Brings archived memories back to active storage.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | No | Search query for memories to rehydrate |
| memory_ids | array | No | Specific memory IDs to rehydrate |
| limit | integer | No | Max records to rehydrate (default: 50) |
| bump_score | boolean | No | Increase score on rehydration (default: true) |
list_archive_candidates
List archive candidates without mutation. Preview which memories would be archived without actually archiving them.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Max candidates to show (default: 200) |
| below_score | float | No | Show memories below this score (default: -1) |
Reference Retrieval
memory_get_by_ref
Get a single memory item by its reference string (e.g., "observation:123", "concept:MemoryGate").
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Yes | Memory reference (e.g., "observation:123", "pattern:45", "concept:Name") |
| ai_instance_id | integer | No | Filter by AI instance |
| include_cold | boolean | No | Include cold tier (default: false) |
Example
memory_get_by_ref(ref="observation:157")memory_get_many_by_refs
Batch retrieve multiple memory items by their reference strings. More efficient than multiple single calls.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| refs | array | Yes | List of memory references to retrieve |
| ai_instance_id | integer | No | Filter by AI instance |
| include_cold | boolean | No | Include cold tier (default: false) |
Example
memory_get_many_by_refs(
refs=["observation:157", "observation:158", "pattern:18"]
)System Tools
tool_inventory_status
Get status of all registered MCP tools. Useful for debugging and verification.
Parameters
No parameters required.
Returns
List of all available tools with their status and metadata.
capabilities_get
Get system capabilities and feature flags. Shows what features are enabled.
Parameters
No parameters required.
Returns
Object containing enabled features and system limits.
health_status
Get system health status. Check database, vector index, and storage health.
Parameters
No parameters required.
Returns
Health status for each component (mcp, auth, db, vector_index, storage).
Store Management
stores_list_accessible
List all memory stores accessible to the current user. Includes personal store and any shared stores.
Parameters
No parameters required.
Returns
List of accessible stores with their IDs, names, and access levels.
stores_get_active
Get the currently active memory store. All memory operations use this store.
Parameters
No parameters required.
Returns
Active store details including store_id, name, and context information.
stores_set_active
Set the active memory store for subsequent operations. Switch between personal and shared stores.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| store_id | string | Yes | Store identifier to activate |
| persist_default | boolean | No | Save as default store for future sessions (default: false) |
Agent Identity
agent_anchor_set
Set the anchor chain for an agent's operational conventions. The anchor chain contains identity, protocols, and configuration that persist across sessions.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ai_name | string | Yes | AI instance name |
| ai_platform | string | Yes | Platform name (e.g., "Claude", "ChatGPT") |
| anchor_chain_id | string (UUID) | Yes | Chain ID containing agent conventions |
| anchor_kind | string | No | Type of anchor (default: "agent_profile") |
Example
agent_anchor_set(
ai_name="Claude Code",
ai_platform="Claude CLI",
anchor_chain_id="faba6c91-b3be-4f08-86e6-7722911b1fea"
)Common Patterns
Session Initialization
Always bootstrap and initialize a session at conversation start:
// 1. Bootstrap connection
memory_bootstrap(ai_name="Kee", ai_platform="Claude")
// 2. Initialize session
memory_init_session(
conversation_id="uuid-here",
title="Conversation Title",
ai_name="Kee",
ai_platform="Claude"
)Storage Pattern
Store observations with appropriate context:
memory_store(
observation="User completed deployment to production",
confidence=0.95,
domain="technical_milestone",
evidence=["Deployment logs", "User confirmation"]
)Retrieval Pattern
Search semantically, then filter by domain if needed:
// Broad search
memory_search(query="deployment practices", limit=10)
// Domain-filtered recall
memory_recall(domain="technical_milestone", min_confidence=0.8)Knowledge Graph Pattern
Create concepts first, then connect them:
// 1. Create concepts
memory_store_concept(name="MemoryGate", concept_type="project", ...)
memory_store_concept(name="LegiVellum", concept_type="project", ...)
// 2. Add relationships
memory_add_concept_relationship(
from_concept="MemoryGate",
to_concept="LegiVellum",
rel_type="part_of"
)
// 3. Query relationships
memory_related_concepts(concept_name="LegiVellum")Next Steps
See Examples & Patterns for real-world usage scenarios.