Neo4j Memory Recall

Neo4j Memory Recall

When to use

• User references a person, project, or topic you may have discussed before
• You need facts from previous sessions not in the current conversation
• User asks "do you remember...", "last time we talked about...", or "what do you know about..."
• You are about to compose a message or email to someone and need relationship context
• User asks a question that might be answered by previously stored knowledge
• You want to check if you already have information before searching externally

Workflow

Preferred native tools

Use the built-in Neo4j-backed OpenClaw tools first:

1. Run memory_search with the user question or the key entity/topic
2. If a hit looks relevant, run memory_get on the returned pseudo-path for more detail
3. Use entity_lookup when the user is asking directly about one graph entity
4. Use graph_query only for relationship-heavy questions that need custom traversal

Basic recall

1. Extract the key entity or topic from the user message
2. Prefer memory_search; use the bridge endpoint below only as a fallback or for low-level debugging
3. Inject the returned context into your response
4. If nothing is found, proceed normally and note you have no prior context

curl -s -X POST http://localhost:7575/memory/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Sarah Kim",
    "limit": 10
  }'

Recall with reasoning traces

Include reasoning history (tool calls, decisions) for audit or debugging:

curl -s -X POST http://localhost:7575/memory/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Q3 roadmap decision",
    "limit": 10,
    "include_reasoning": true
  }'

Selective context injection

For the most token-efficient context injection, use the /memory/context endpoint which returns a pre-formatted, relevance-ranked context block:

curl -s -X POST http://localhost:7575/memory/context \
  -H "Content-Type: application/json" \
  -d '{
    "message": "The full user message to find context for",
    "max_tokens": 2000
  }'

This returns a Markdown-formatted context block with:

• Matched entities and their properties
• Relationship graph (1-hop traversal)
• Relevant observations
• Recent reasoning traces

Response format

/memory/recall response

{
  "results": [
    {
      "name": "Sarah Kim",
      "role": "Product Manager",
      "company": "Acme Corp",
      "_labels": ["Person"],
      "_score": 2.45,
      "_relationships": [
        { "type": "WORKS_AT", "target_labels": ["Organization"], "target_name": "Acme Corp" },
        { "type": "PARTICIPATED_IN", "target_labels": ["Event"], "target_name": "ProductConf 2026" }
      ]
    }
  ],
  "count": 1,
  "query": "Sarah Kim"
}

/memory/context response

{
  "context": "## Known Entities\n[Person] Sarah Kim: {'role': 'PM', 'company': 'Acme'}\n  Sarah Kim -WORKS_AT-> Acme Corp\n\n## Observations\n- Prefers async communication",
  "entities_used": 3,
  "reasoning_traces": 1,
  "token_estimate": 145
}

Guidelines

• Recall BEFORE answering questions about people, projects, or past events
• Prefer memory_search + memory_get over raw curl when the native tools are available
• Use /memory/context for system prompt injection (most token-efficient)
• Use /memory/recall when you need raw structured data for processing
• If recall returns nothing, say so — don't hallucinate prior context
• Use include_reasoning: true only when the user asks about past decisions or audit trails
• Keep limit reasonable (5–15) to avoid overwhelming context
• The _score field indicates relevance — higher is better