MCP Tools

Engram provides 11 MCP tools through a TypeScript server. The server translates calls into JSON requests to the Rust core via Unix socket.

memory_store

Saves a new memory record. When cosine similarity > 0.95 with an existing record, updates it instead of creating a duplicate.

{
  "context": "Situation where the action occurred",
  "action": "Decision or action taken",
  "result": "Result or outcome",
  "memory_type": "decision",
  "tags": "auth,refactor",
  "project": "my-project"
}

Parameter	Type	Required	Description
`context`	string	yes	Situation context
`action`	string	yes	Action or decision
`result`	string	yes	Result
`memory_type`	enum	no	`decision` (default), `pattern`, `bugfix`, `context`, `antipattern`
`tags`	string	no	Comma-separated tags
`project`	string	no	Project identifier

memory_search

Finds relevant records using hybrid search: 70% vector (HNSW cosine) + 30% full-text (BM25 FTS5).

{
  "query": "authentication middleware architecture",
  "limit": 10,
  "project": "my-project"
}

Parameter	Type	Required	Description
`query`	string	yes	Search query
`limit`	number	no	Maximum results (default 10)
`project`	string	no	Filter by project

memory_judge

Rates a memory's quality. Feeds the Q-Learning router to improve future searches.

{
  "memory_id": "uuid",
  "query": "the query that found this memory",
  "score": 0.8
}

Parameter	Type	Required	Description
`memory_id`	string	yes	Memory UUID
`query`	string	no	Search context
`score`	number	no	Score from 0.0 to 1.0

Scoring guide:

0.8-1.0 — directly solved the problem
0.5-0.7 — useful context, partially relevant
0.1-0.4 — tangentially related, not very helpful

memory_status

Returns system status: memory count, index size, pending judgments.

{}

memory_config

Reads current configuration. Writing config via MCP is not supported (error code 6008).

{
  "action": "get"
}

Parameter	Type	Required	Description
`action`	enum	no	`get` (default) or `set`

memory_export

Exports all active memories as portable JSON. Binary fields (embeddings, indexed, superseded_by) are excluded.

{}

memory_import

Imports memories from exported JSON. Merge mode: skips duplicates by ID. Imported memories get indexed=false and require reindexing.

{
  "version": 1,
  "memories": [
    {
      "id": "uuid",
      "memory_type": "decision",
      "context": "...",
      "action": "...",
      "result": "...",
      "score": 0.0,
      "tags": "tag1,tag2",
      "project": "my-project",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z",
      "used_count": 0
    }
  ]
}

Parameter	Type	Required	Description
`version`	number	yes	Export format version (must be 1)
`memories`	array	yes	Array of memory objects

memory_consolidate_preview

Finds deduplication candidates without applying changes. Does not call LLM.

{
  "stale_days": 30,
  "min_score": 0.3
}

Parameter	Type	Required	Description
`stale_days`	number	no	Stale threshold (days)
`min_score`	number	no	Minimum score

memory_consolidate

Analyzes candidates with LLM. Returns merge/keep recommendations.

{
  "stale_days": 30,
  "min_score": 0.3
}

memory_consolidate_apply

Applies consolidation recommendations: merge, delete, archive.

{
  "stale_days": 30,
  "min_score": 0.3
}

memory_insights

Manages derived knowledge (insights) generated by the trainer.

{
  "action": "list"
}

Parameter	Type	Required	Description
`action`	enum	no	`list` (default), `generate`, `delete`
`id`	string	no	Insight UUID (for `delete` action)

Actions:

list — show all active insights
generate — run trainer to analyze patterns
delete — delete insight by ID (verifies memory_type = 'insight')

MCP Tools

On this page