Neo4j Memory Store

Neo4j Memory Store

When to use

• You learn a new fact about a person, company, project, or topic
• The user tells you something they want you to remember
• You encounter a named entity (person, place, event, organization) worth tracking
• You make an observation about a pattern, preference, or relationship
• You want to record a relationship between two entities (e.g., "Alice works at Acme")

What you can store

Entities (POLE+O model)

Store structured entities with typed relationships:

• Person: People, contacts, team members
• Organization: Companies, teams, groups
• Location: Places, offices, cities, countries
• Event: Meetings, milestones, incidents, dates
• Object: Projects, documents, tools, concepts, books, articles — anything else

Observations

Store unstructured observations about an entity — notes, impressions, or context that doesn't fit a structured property.

Messages

Store conversation messages for short-term memory within a session.

Workflow

Preferred native tools

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

1. Run memory_store for normal writes
2. Use reasoning_trace for provenance or audit events
3. Fall back to the bridge HTTP examples below only when you explicitly need the raw API

Storing an entity

1. Identify the entity type (Person, Organization, Location, Event, or Object)
2. Extract properties (name is required; add role, description, etc. as available)
3. Identify relationships to other entities
4. Prefer memory_store; use the bridge endpoint below as a low-level fallback:

curl -s -X POST http://localhost:7575/memory/store \
  -H "Content-Type: application/json" \
  -d '{
    "type": "entity",
    "data": {
      "label": "Person",
      "properties": {
        "name": "Sarah Kim",
        "role": "Product Manager",
        "company": "Acme Corp"
      },
      "relationships": [
        {
          "type": "WORKS_AT",
          "targetLabel": "Organization",
          "targetName": "Acme Corp"
        }
      ]
    },
    "session_id": "current-session-id",
    "channel": "telegram"
  }'

Storing an observation

curl -s -X POST http://localhost:7575/memory/store \
  -H "Content-Type: application/json" \
  -d '{
    "type": "observation",
    "data": {
      "content": "Prefers async communication over meetings",
      "subject": "Sarah Kim"
    },
    "session_id": "current-session-id"
  }'

Storing a message

curl -s -X POST http://localhost:7575/memory/store \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "data": {
      "role": "user",
      "content": "Can you look into the Q3 roadmap?"
    },
    "session_id": "current-session-id",
    "channel": "slack"
  }'

Common relationship types

Use these relationship types to connect entities:

Response format

{
  "status": "stored",
  "node_id": "entity-sarah-kim-a1b2c3",
  "merged": false
}

• merged: true means an existing entity was updated (not duplicated)
• merged: false means a new entity was created

Guidelines

• Always use the person's full name when known
• Prefer the native memory_store tool when available so the model stays inside the standard OpenClaw tool loop
• Include the session_id to enable cross-session tracking
• Include the channel to enable cross-channel memory
• Store relationships at creation time — don't create orphan entities
• Prefer specific relationship types over generic RELATED_TO
• When the same entity appears with different names (e.g., "Sarah", "Sarah Kim"), store under the most complete name