MCP Tools

Store a new memory. The content is embedded into a 384-dimensional vector and indexed for semantic search.

Example

// Store a semantic fact
{
  "content": "The API server runs on Fastify with WAL-mode SQLite",
  "type": "semantic",
  "importance": 0.85,
  "concept": "Tech stack — API"
}

// Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "semantic",
  "content": "The API server runs on Fastify with WAL-mode SQLite",
  "importance": 0.85,
  "createdAt": "2025-03-21T10:00:00.000Z"
}

Assemble the most relevant context from all memories for a given query. Returns formatted context ready to use in AI prompts. This is the primary tool for giving AI models access to their memories.

Example

// Recall context for a new conversation
{
  "query": "Working on the Engram API server — what do I need to know?",
  "maxTokens": 2000
}

// Response
{
  "context": "[NEURAL MEMORY CONTEXT]\n[KNOWLEDGE]\n• The API server runs on Fastify...",
  "memoriesUsed": 4,
  "latencyMs": 18,
  "memories": [
    {
      "id": "a1b2c3d4-...",
      "type": "semantic",
      "score": "0.940",
      "source": "claude-code"
    }
  ]
}

// Progressive mode — grouped by phase
{
  "query": "API server setup",
  "progressive": true
}

// Response
{
  "context": "[NEURAL MEMORY CONTEXT]\n...",
  "memoriesUsed": 6,
  "latencyMs": 24,
  "phases": {
    "vector": { "count": 4, "memories": [/* high-confidence direct matches */] },
    "graph":  { "count": 2, "memories": [/* graph-expanded neighbors */] }
  }
}

Pure semantic search — returns memories ordered by vector similarity only, without recency or importance weighting. Useful for explicit knowledge lookup.

Example

// Find facts about the database layer
{
  "query": "SQLite WAL mode performance",
  "types": ["semantic"]
}

// Response
{
  "count": 1,
  "results": [
    {
      "id": "a1b2c3d4-...",
      "type": "semantic",
      "content": "SQLite WAL mode enables 10k+ writes/sec",
      "importance": 0.8,
      "source": "claude-code",
      "createdAt": "2025-03-21T..."
    }
  ]
}

Convenience wrapper for store_memory that defaults to type=semantic. Designed for adding factual knowledge to the graph.

Example

// Add a knowledge node
{
  "concept": "Vector Index",
  "content": "In-memory cosine scan over FP16 embeddings; no ANN index",
  "importance": 0.80
}

// Response
{
  "id": "a1b2c3d4-...",
  "concept": "Vector Index",
  "message": "Knowledge stored"
}

Returns aggregate statistics about the memory store — counts by type, source, graph metrics.

No parameters required.

Example response

{
  "total": 1247,
  "byType": {
    "episodic": 680,
    "semantic": 412,
    "procedural": 155
  },
  "bySource": {
    "claude-code": 820,
    "ollama": 310,
    "openclaw": 117
  },
  "indexSize": 1247,
  "graphNodes": 1247,
  "graphEdges": 2843
}

Archive (soft-delete) memories from the brain. Memories are excluded from future recall but not permanently destroyed.

Example

// Archive specific memories
{
  "ids": ["a1b2c3d4-...", "e5f6a7b8-..."],
  "reason": "Outdated deployment instructions"
}

// Response
{
  "archived": 2,
  "reason": "Outdated deployment instructions",
  "message": "Archived 2 memory(ies)"
}

Run a memory decay sweep — evaluates all memories and archives stale ones based on the decay policy. Also triggers auto-consolidation of old episodic memories if enabled.

Example

// Preview what would be archived (dry run)
{
  "dryRun": true
}

// Response
{
  "scannedCount": 101,
  "archivedCount": 12,
  "archivedIds": ["a1b2c3d4-...", "e5f6g7h8-...", "..."],
  "decayedCount": 34,
  "protectedCount": 8,
  "consolidatedCount": 0,
  "newSemanticIds": [],
  "durationMs": 45,
  "mode": "dry-run",
  "message": "Dry run: would archive 12 memories, decay 34, consolidate 0"
}

View or update the memory decay policy configuration. Controls how aggressively memories are forgotten and when auto-consolidation runs.

Example

// Get current policy
{ "action": "get" }

// Update: slower decay, higher threshold
{
  "action": "update",
  "halfLifeDays": 14,
  "archiveThreshold": 0.1
}

// Response
{
  "policy": {
    "halfLifeDays": 14,
    "archiveThreshold": 0.1,
    "decayIntervalMs": 3600000,
    "batchSize": 200,
    "importanceDecayRate": 0.01,
    "importanceFloor": 0.05,
    "consolidation": {
      "enabled": true,
      "minClusterSize": 3,
      "similarityThreshold": 0.6,
      "minEpisodicAgeMs": 86400000
    },
    "protectionRuleCount": 4
  },
  "message": "Policy updated"
}

Check a memory for contradictions with existing memories, or list all unresolved contradictions. Detects negation, value changes, temporal overrides, and opposite sentiment.

Example

// Check a specific memory
{ "memoryId": "a1b2c3d4-..." }

// Response
{
  "hasContradictions": true,
  "contradictions": [
    {
      "newMemoryId": "a1b2c3d4-...",
      "existingMemoryId": "e5f6g7h8-...",
      "similarity": 0.872,
      "confidence": 0.637,
      "signals": [
        { "type": "negation", "description": "Content contains negation...", "weight": 0.75 }
      ],
      "suggestedStrategy": "keep_newest"
    }
  ],
  "candidatesChecked": 5,
  "latencyMs": 18
}

// List all unresolved (no memoryId)
{}

// Response
{
  "count": 2,
  "contradictions": [
    {
      "confidence": 0.637,
      "metadata": { "signals": ["negation"], "suggestedStrategy": "keep_both" },
      "source": { "id": "...", "content": "The app uses MongoDB...", "type": "semantic" },
      "target": { "id": "...", "content": "The app uses PostgreSQL...", "type": "semantic" }
    }
  ]
}

Resolve a contradiction between two memories using a strategy. Removes the contradicts graph edge and optionally archives one of the memories.

Example

// Resolve by keeping the newest memory
{
  "sourceId": "a1b2c3d4-...",
  "targetId": "e5f6g7h8-...",
  "strategy": "keep_newest"
}

// Response
{
  "resolved": true,
  "strategy": "keep_newest",
  "keptId": "a1b2c3d4-...",
  "archivedId": "e5f6g7h8-...",
  "message": "Contradiction resolved via keep_newest. Kept: a1b2c3d4-..., Archived: e5f6g7h8-..."
}

Get the status of the embedding model — shows current model, dimension, and how many memories need re-embedding (stale or legacy).

No parameters required.

Example response

{
  "currentModel":      "Xenova/all-MiniLM-L6-v2",
  "currentDimension":  384,
  "totalEmbedded":     1247,
  "currentModelCount": 1200,
  "staleCount":        0,
  "legacyCount":       47,
  "needsReEmbed":      true,
  "message": "47 memories need re-embedding (0 stale, 47 legacy)"
}

Re-embed memories with the current embedding model. Use after switching models to update stale vectors. Can be slow for large stores.

Example

// Re-embed only stale memories
{ "onlyStale": true }

// Response
{
  "total":      47,
  "processed":  47,
  "failed":     0,
  "failedIds":  [],
  "durationMs": 2340,
  "model":      "Xenova/all-MiniLM-L6-v2",
  "message":    "Re-embedded 47 memories in 2340ms"
}

Get the vector index status — how it was loaded (fast disk cache or full DB rebuild), entry count, and startup performance.

No parameters required.

Example response

{
  "loadedFrom":       "disk",
  "entryCount":       1247,
  "dimension":        384,
  "indexPath":        "/data/engram.db.index",
  "indexFileExists":  true,
  "incrementalCount": 3,
  "initDurationMs":   45,
  "message": "Index loaded from disk cache (1247 entries, 3 added incrementally, 45ms)"
}

Get the tag cloud (all unique tags with counts), or get memories for a specific tag.

Example

// Get tag cloud
{}
// Response: { "count": 8, "tags": [{ "tag": "typescript", "count": 42 }, ...] }

// Get memories by tag
{ "tag": "typescript", "limit": 5 }
// Response: { "tag": "typescript", "count": 5, "memories": [...] }

Add or remove a tag on a memory.

Example

// Add a tag
{ "memoryId": "a1b2c3d4-...", "tag": "important" }
// Response: { "id": "a1b2c3d4-...", "tags": ["existing", "important"], "message": "Tag \"important\" added" }

// Remove a tag
{ "memoryId": "a1b2c3d4-...", "tag": "outdated", "action": "remove" }

List all registered Engram plugins with their hooks and metadata.

No parameters required.

Example response

{
  "count": 1,
  "plugins": [
    {
      "id": "my-org/logger",
      "name": "Memory Logger",
      "version": "1.0.0",
      "hooks": ["onStore", "onRecall"],
      "registeredAt": "2026-03-25T..."
    }
  ],
  "message": "1 plugin(s) registered"
}

Subscribe a URL to receive HTTP POST callbacks when memory events occur. Supports HMAC-SHA256 signing.

Example

{
  "url": "https://example.com/engram-hook",
  "events": ["stored", "contradiction"],
  "description": "Notify on new memories and conflicts"
}

// Response
{
  "id": "a1b2c3d4-...",
  "url": "https://example.com/engram-hook",
  "events": ["stored", "contradiction"],
  "active": true,
  "message": "Webhook subscribed: a1b2c3d4-..."
}

List all webhook subscriptions with their status, event filters, and failure counts.

No parameters required.

Example response

{
  "count": 2,
  "webhooks": [
    {
      "id": "a1b2c3d4-...",
      "url": "https://example.com/engram-hook",
      "events": ["stored", "contradiction"],
      "active": true,
      "failCount": 0,
      "description": "Notify on new memories"
    }
  ]
}

Get memory reflection tasks to reason over. Engram selects and summarizes your memories and returns one prompt per reflection type — it runs no LLM itself. YOU analyze each prompt and call store_reflection with any genuine insight.

Takes no parameters.

// Returns one task per configured reflection type
[
  {
    "type": "pattern",
    "relatedMemoryIds": ["a1b2...", "c3d4..."],
    "prompt": "You are analyzing a collection of AI memories...\nTASK: Identify recurring behavioral patterns..."
  }
]

Store an insight you generated from request_reflection. Saved as a semantic memory tagged reflection:<type>. Do not call this for empty or NO_INSIGHT results.

Retrieve stored reflection insights, newest first. The type filter is applied in SQL, so the limit is applied after filtering.