openclaw-graphiti-memory - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #llm #golang #machine-learning #rust #java #cli #kubernetes #vue #security #ios #mcp #openai

openclaw-graphiti-memory

(★ 103)

Hybrid memory system for OpenClaw using Graphiti temporal knowledge graph

File Explorer

Download Latest Version (.zip)

- com.openclaw.graphiti-file-sync.plist
- com.openclaw.graphiti-sync.plist
- graphiti-context.sh
- graphiti-import-files.py
- graphiti-log.sh
- graphiti-search.sh
- graphiti-sync-sessions.py
- graphiti-watch-files.py
- memory-hybrid-search.sh
- memory-status.sh
- patch-shared-memory.py
- agent-roster.example.md
- graphiti-memory.md
- infrastructure.example.md
- user-profile.example.md
- SKILL.md
- shared-memory-snippet.md
.gitignore
docker-compose.yml
install.sh
LICENSE
README.md

# Installation Guide

1. Get the code

git clone https://github.com/clawdbrunner/openclaw-graphiti-memory

Downloads the entire project code from GitHub to your computer.

cd openclaw-graphiti-memory

Moves into the project folder you just downloaded.

2. Docker

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

cp docker-compose.yml ~/.openclaw/services/graphiti/

Runs the command against the services defined in the compose file.

docker compose up -d

Builds and starts all defined containers (server, database, etc.) at once, in the background.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenClaw Hybrid Memory: QMD + Graphiti + Shared Files

A complete three-layer memory system for [OpenClaw](https://openclaw.ai) multi-agent setups.

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Agent Memory                       │
│                                                      │
│  Layer 1: Private Files (QMD)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ piper/   │ │ paige/   │ │ dean/    │  ...       │
│  │ memory/  │ │ memory/  │ │ memory/  │            │
│  └──────────┘ └──────────┘ └──────────┘            │
│  Per-agent vector search via memory_search           │
│                                                      │
│  Layer 2: Shared Files (shared/)                     │
│  ┌──────────────────────────────────┐               │
│  │ user-profile.md                  │               │
│  │ agent-roster.md                  │               │
│  │ infrastructure.md                │               │
│  │ graphiti-memory.md               │               │
│  └──────────────────────────────────┘               │
│  Symlinked into each agent workspace as shared/      │
│  Indexed by QMD alongside private files              │
│                                                      │
│  Layer 3: Shared Knowledge Graph (Graphiti)          │
│  ┌──────────────────────────────────┐               │
│  │ openclaw-clawd  (write own)     │               │
│  │ openclaw-piper  (write own)     │               │
│  │ user-main      (orchestrator)  │               │
│  │ system-shared   (orchestrator)  │               │
│  └──────────────────────────────────┘               │
│  Cross-group search for temporal facts               │
└─────────────────────────────────────────────────────┘
```

## Three Layers

| Layer | What | Best For | Mutability |
|-------|------|----------|------------|
| **Private Files** | Agent's own `memory/` dir | Private notes, task logs, local state | Agent writes freely |
| **Shared Files** | `shared/` dir (symlinked) | Stable reference docs (profiles, roster) | Orchestrator maintains |
| **Shared Graph** | Graphiti knowledge graph | Temporal facts, cross-agent knowledge | Agents write to own group |

### When to use which

- **"What's the user's email?"** → Shared files (`user-profile.md`) or Graphiti
- **"What did I log yesterday?"** → Private files (`memory_search`)
- **"What did Piper find about that invoice?"** → Graphiti (cross-group search)
- **"Who handles security?"** → Shared files (`agent-roster.md`)
- **"When did we change the deployment config?"** → Graphiti (temporal)

---

## Setup

### Prerequisites

- [OpenClaw](https://openclaw.ai) installed and configured
- Docker (for Graphiti + Neo4j)
- An OpenAI API key (for Graphiti embeddings)

### 1. Install Graphiti Stack

```bash
git clone https://github.com/clawdbrunner/openclaw-graphiti-memory.git
cd openclaw-graphiti-memory

# Copy docker-compose to your services directory
mkdir -p ~/.openclaw/services/graphiti
cp docker-compose.yml ~/.openclaw/services/graphiti/

# Set your OpenAI key
export OPENAI_API_KEY="sk-..."

# Start the stack
cd ~/.openclaw/services/graphiti
docker compose up -d
```

### 2. Configure QMD in OpenClaw

Add to `~/.openclaw/openclaw.json` under `agents.defaults`:

```json
{
  "memorySearch": {
    "enabled": true,
    "sources": ["memory", "sessions"],
    "provider": "gemini",
    "model": "gemini-embedding-001",
    "sync": {
      "onSessionStart": true,
      "watch": true
    }
  }
}
```

### 3. Set Up Shared Directory

```bash
# Copy scripts to OpenClaw scripts directory
mkdir -p ~/.openclaw/scripts
cp scripts/*.sh scripts/*.py ~/.openclaw/scripts/
chmod +x ~/.openclaw/scripts/*.sh

# Copy shared reference files
mkdir -p ~/.openclaw/shared
cp shared-files/*.md ~/.openclaw/shared/

# Symlink into each agent's workspace
for agent_dir in ~/.openclaw/agents/*/; do
  agent=$(basename "$agent_dir")
  [[ "$agent" == "_shared" || "$agent" == "_template" ]] && continue
  ln -sf ~/.openclaw/shared "$agent_dir/shared"
done
```

### 4. Add Memory Instructions to Agent AGENTS.md

Add the shared memory section to each agent's AGENTS.md. See `templates/shared-memory-snippet.md` for a copy-paste template, or use the patch script:

```bash
python3 scripts/patch-shared-memory.py
```

### 5. Seed Shared Context

```bash
# Seed user profile
scripts/graphiti-log.sh user-main system "System" "User lives in Example City, EST timezone."

# Seed agent roster
scripts/graphiti-log.sh system-shared system "System" "Agent team: Clawd (orchestrator), Piper (email), Paige (finance)..."
```

---

## Scripts

### For Agents (`scripts/`)

| Script | Purpose |
|--------|---------|
| `graphiti-search.sh "query" [group_id] [max]` | Search knowledge graph |
| `graphiti-log.sh <agent_id> <role> <name> "content"` | Log facts to own group |
| `graphiti-context.sh "task" [agent_id]` | Get full context for a task |

### For Setup (`scripts/`)

| Script | Purpose |
|--------|---------|
| `memory-hybrid-search.sh "query"` | Search QMD + Graphiti together |
| `graphiti-import-files.py` | Bulk import files into Graphiti |
| `graphiti-sync-sessions.py` | Sync session transcripts to Graphiti |
| `graphiti-watch-files.py` | Watch files and auto-sync to Graphiti |
| `patch-shared-memory.py` | Patch all agent AGENTS.md files |

---

## Graphiti Groups

| Group | Owner | Purpose |
|-------|-------|---------|
| `openclaw-<agent_id>` | Each agent | Agent's own discoveries and decisions |
| `user-main` | Orchestrator | User profile, preferences, contacts |
| `system-shared` | Orchestrator | Agent roster, infrastructure, active projects |

### Rules

1. Agents write to their **own group only**
2. Agents read **cross-group** (omit `group_id` for global search)
3. Only the orchestrator writes to `user-main` and `system-shared`
4. Shared files in `shared/` are **read-only** for agents — report updates to orchestrator

---

## Docker Compose

The included `docker-compose.yml` runs:

- **Graphiti API** (port 8001) — REST API for the knowledge graph
- **Neo4j** (ports 7474/7687) — Graph database backend

Environment variables:
- `OPENAI_API_KEY` — Required for embeddings
- `MODEL_NAME` — LLM for entity extraction (default: `gpt-4.1-mini`, recommend `gpt-4.1`)

---

## Cost

- **QMD:** Free (local, uses Gemini embeddings which are free tier)
- **Graphiti:** OpenAI API costs for entity extraction during ingestion only
  - `gpt-4.1`: ~$2/M input, $8/M output tokens
  - Searches are free (local Neo4j queries)
  - Typical cost: < $1/month for a 20-agent setup

---

## License

MIT