Tools
Walle Memory
By GraphRAG memory backend for self-improving AI agents — Kuzu graph + sqlite-vec, 15 MCP tools, event-driven learn/abstract/reflect, OpenClaw plugin.
Install
pip install -eConfiguration Example
url = "http://127.0.0.1:8002"
timeout = 3
token_file = "~/.config/walle/token"
namespace = "frenude-local"
agent_id = "codex"README
# walle-memory
GraphRAG memory backend for self-improving agents.
[](https://opensource.org/licenses/MIT)
> Built by [WALL·E](https://github.com/frenude) — a personal AI agent that
> needs to actually remember things across sessions. This repo is what it
> uses for long-term memory.
- **Storage**: Kuzu (graph) + SQLite (FTS5 + sqlite-vec, 3072-d embeddings)
- **Retrieval**: vector / FTS / hybrid / HippoRAG-2-style Personalized PageRank
- **Learning**: 3-level reflection tree — Episode → Lesson → Principle
- **Event-driven triggers**: fresh Episodes can trigger `learn`; Failures trigger online RCA
- **Beliefs**: confidence + evidence count + exponential decay + verify loop
- **Contradictions**: detected on new Lessons, logged, graphed, down-weighted
- **Gaps**: Failures produce a prioritized "next to learn" queue
- **Transport**: FastAPI + MCP SSE, 15 tools, plus plain HTTP fallback for curl
See `DESIGN.md` for the full specification.
## Tools
| tool | purpose |
|---|---|
| `ingest` | store a raw Episode / Failure; embed + FTS + background entity extract |
| `search` | `mode=ppr` (default) / `vector` / `fts` / `hybrid`, with `evidence_path` |
| `active_recall` | current context → related memories, contradiction warnings, and follow-up Gaps |
| `graph_walk` | BFS from a node along a relation, for debug / exploration |
| `trace_cause` | reverse-walk `caused` edges from a Failure to its root causes |
| `find_contradictions` | list unresolved contradictions between Lessons |
| `learn` | L0→L1: cluster recent Episodes and LLM-summarize into Lessons |
| `abstract` | L1→L2: fold Lessons into cross-domain Principles |
| `reflect` | Generative-Agents-style insight + gap + contradiction pass |
| `verify` | boost / penalize a Lesson's confidence based on observed outcome |
| `next_to_learn` | top-priority Gaps (known unknowns) |
| `curriculum_push` | push up to three urgent Gaps with one-line learning prompts |
| `stats` | counts, avg confidence, contradiction rate, growth curves |
| `list` | filter nodes by `type` / `tags` / `status` |
| `delete` | remove a node (optionally cascade) |
All tool responses have shape `{ok, request_id, duration_ms, data | error + traceback}`.
## Running locally
```bash
# Python 3.12 required (Kuzu has no 3.14 wheels yet)
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
# optional — if unset, LLM/extract/learn steps degrade gracefully (Episodes still ingest)
export OPENROUTER_API_KEY=sk-or-...
export HTTP_PROXY=http://127.0.0.1:7890 # optional; also read as HTTPS_PROXY
# by default writes to ~/.walle-memory/data and ~/.walle-memory/logs
WALLE_DATA_DIR=/tmp/walle-data python -m walle_memory.server
```
Then:
```bash
curl -s http://127.0.0.1:8000/healthz
curl -s -X POST http://127.0.0.1:8000/tool/stats -d '{}'
curl -s -X POST http://127.0.0.1:8000/tool/ingest \
-H 'Content-Type: application/json' \
-d '{"text":"SSE keepalive every 20s avoids Cloudflare 524","tags":["sse"]}'
curl -s -X POST http://127.0.0.1:8000/tool/search \
-H 'Content-Type: application/json' \
-d '{"query":"keepalive","mode":"hybrid"}'
```
MCP SSE lives at `GET /sse` with message POSTs to `/messages/`.
## OpenClaw integration
This repo ships an `openclaw-plugin/` directory with everything needed to wire
walle-memory into [OpenClaw](https://github.com/openclaw/openclaw) as a memory
backend:
- `openclaw-plugin/skills/` — four ready-to-drop skills (`memory-retrieval`,
`memory-sync`, `curate-memory`, `walle-memory-diagnostics`)
- `openclaw-plugin/config/mcp-servers.example.json` — MCP server registration
- `openclaw-plugin/designs/` — original design docs (architecture / Day-1 brief
/ CC review)
Minimum wiring:
```bash
# 1. start walle-memory locally (port 8002)
docker compose up -d
# 2. register the MCP server in ~/.openclaw/openclaw.json
# (merge the snippet from openclaw-plugin/config/mcp-servers.example.json)
# 3. drop one or more skills into ~/.openclaw/workspace/skills/
cp openclaw-plugin/skills/memory-retrieval.md \
~/.openclaw/workspace/skills/memory-retrieval/SKILL.md
```
After that any OpenClaw agent gets the 15 walle tools as `walle-memory__*` MCP
tools, plus the four skill workflows for active recall / curation / sync /
diagnostics.
## Running tests
```bash
source .venv/bin/activate
pytest # ~5s, 32 tests
pytest --cov=walle_memory # coverage report (~74% at head)
```
Tests isolate storage per-test and mock the LLM / embedding layer so the
full ingest / search / learn / contradiction paths run against real
SQLite + Kuzu without network access.
## CLI
Install the local command package with pipx:
```bash
pipx install -e . --force
```
The install exposes:
- `walle`: shell CLI for the local HTTP service
- `walle-mcp`: reserved stdio bridge entry point for Phase 1.5
Configuration is resolved from flags, then environment, then
`~/.config/walle/config.toml`. Defaults target the Docker service at
`http://127.0.0.1:8002`.
```toml
url = "http://127.0.0.1:8002"
timeout = 3
token_file = "~/.config/walle/token"
namespace = "frenude-local"
agent_id = "codex"
```
Examples:
```bash
walle health
walle stats
walle search "kaon-router gzip" --top-k 3
walle recall "tell me about kaon router cloudflare timeout"
walle ingest -t "Phase 1 CLI smoke test" --tags smoke,cli-test
walle list --type Lesson --limit 5
```
`walle recall` is hook-safe: short prompts, no matches, service errors, and
timeouts print nothing and exit 0. Failures are written to
`~/.config/walle/recall.log`.
## Running in Docker
```bash
# exposes on host 127.0.0.1:8002 → container 8000
export OPENROUTER_API_KEY=sk-or-...
docker compose up --build
```
Image is a multi-stage `python:3.12-slim` build. Data persists under
`~/.walle-memory/{data,logs}` on the host.
Healthcheck (`/healthz`) does a real R/W probe on both SQLite and Kuzu and
fails the container on either outage.
## Notes
- **First cold start is slow** (~30s) because Kuzu creates the 9 node +
11 relationship tables. Subsequent starts are <1s.
- **No API key? Still works.** Episodes ingest and are searchable by FTS / vector
(if you pre-embedded) / hybrid, but `learn` / `abstract` / `reflect` /
contradiction detection / gap mining return empty until a key is configured.
- Scheduler runs 5 cron jobs in-container (learn nightly, decay, dream_gap,
abstract weekly, monthly vacuum/checkpoint). Disable with
`ENABLE_SCHEDULER=false`.
- Event-driven triggers are enabled by default. `EPISODES_PER_LEARN=10`
controls when fresh Episode/Failure ingests queue a background `learn`, and
`ENABLE_EVENT_TRIGGERS=false` disables online triggers while keeping cron.
Failure ingests also run online `trace_cause` and a single-failure Gap pass.
- All HTTP requests use `httpx.AsyncClient(proxy=…)` with the proxy passed
explicitly; set `HTTP_PROXY` or `HTTPS_PROXY` if your environment requires it.
## License
MIT. See [LICENSE](./LICENSE).
## Acknowledgements
- Architecture inspired by [HippoRAG](https://github.com/OSU-NLP-Group/HippoRAG)
(PPR-based retrieval) and Stanford Generative Agents (reflection tree).
- Built on [Kuzu](https://kuzudb.com/) (graph) and
[sqlite-vec](https://github.com/asg017/sqlite-vec) (vector ANN).
tools
Comments
Sign in to leave a comment