recall_memories

Search stored memories using hybrid (keyword + semantic) or semantic-only search modes.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	REQUIRED	-	Search query (1-1000 chars)
`entityTypes`	enum[]	OPTIONAL	all	Filter by entity types
`limit`	number	OPTIONAL	`10`	Max results (1-50)
`searchMode`	enum	OPTIONAL	`hybrid`	Search mode: hybrid, semantic

Search Modes

Mode	Description
`hybrid`	Combines keyword matching with semantic similarity (recommended)
`semantic`	Pure semantic similarity search

Example Request

{
  "query": "user preferences for development tools",
  "entityTypes": ["person", "preference"],
  "limit": 10,
  "searchMode": "hybrid"
}

Response

Compact Mode (Default)

When COMPACT_RESPONSES=true (default), responses use short keys to reduce token usage by 40-60%:

{"n":3,"e":[{"n":"Jeff","t":"person","m":[{"c":"prefers TypeScript over JavaScript","s":0.92},{"c":"uses VS Code as primary editor","s":0.85}]},{"n":"Development Setup","t":"preference","m":[{"c":"dark mode enabled by default","s":0.78}]}]}

Key mapping: n=count/name, e=entities, t=type, m=memories, c=content, s=score

Verbose Mode

When COMPACT_RESPONSES=false:

{
  "query": "user preferences for development tools",
  "totalMemories": 3,
  "entities": [
    {
      "entityName": "Jeff",
      "entityType": "person",
      "memories": [
        {
          "content": "prefers TypeScript over JavaScript",
          "source": "conversation",
          "confidence": 1.0,
          "score": 0.92
        },
        {
          "content": "uses VS Code as primary editor",
          "source": "conversation",
          "confidence": 1.0,
          "score": 0.85
        }
      ]
    },
    {
      "entityName": "Development Setup",
      "entityType": "preference",
      "memories": [
        {
          "content": "dark mode enabled by default",
          "source": "manual",
          "confidence": 1.0,
          "score": 0.78
        }
      ]
    }
  ]
}

Use Cases

Find User Context

{
  "query": "what does the user prefer",
  "entityTypes": ["person", "preference"],
  "limit": 20
}

Project Information

{
  "query": "database technology stack",
  "entityTypes": ["project", "concept"],
  "searchMode": "semantic"
}

Recent Decisions

{
  "query": "decisions made about architecture",
  "limit": 10
}

Score Interpretation

Score Range	Meaning
0.9 - 1.0	Highly relevant match
0.7 - 0.9	Good match
0.5 - 0.7	Moderate relevance
< 0.5	Weak match

Errors

Error	Cause	Fix
Embedding service not configured	Missing `OPENAI_API_KEY` or Ollama config	Set `OPENAI_API_KEY` or configure `OLLAMA_BASE_URL`
Invalid query length	Query empty or exceeds 1000 chars	Provide query between 1-1000 chars
Invalid limit	Limit outside 1-50 range	Set limit between 1 and 50
Invalid entity type	Unknown entity type in filter	Use valid types: person, concept, project, preference, fact, location, organization
Memory not enabled	`ENABLE_MEMORY` feature flag is false	Set `ENABLE_MEMORY=true`

On this page