openclaw-memory-explorer/README.md

Vector Explorer

vector_explorer is a Rust + GTK desktop viewer for SQLite-backed vector stores. It is designed around OpenClaw's memory layout and can fall back to a generic adapter for similar databases such as NullClaw- or ZeroClaw-style stores that keep chunk text and embeddings in SQLite tables.

Features

• Store overview with detected adapter, file count, chunk count, embedding dimensions, models, and inferred backend features such as FTS5 or sqlite-vec
• Filterable file list with a top-level reset entry to return to the full graph
• Rotatable 3D semantic map based on a lightweight PCA-style projection of embeddings
• Detail panel for the selected chunk or file
• OpenClaw-first schema detection with generic SQLite heuristics for other stores

Supported store layouts

OpenClaw

The first-class adapter targets the documented OpenClaw memory structure:

• files for indexed documents
• chunks for chunk text and stored embeddings
• meta for memory index metadata
• chunks_fts and chunks_vec as optional hybrid-search acceleration tables

The sample main.sqlite in this repository matches that layout.

Generic SQLite vector stores

If the database is not recognized as OpenClaw, the app falls back to schema heuristics:

• Find a table with text/content columns
• Prefer tables that also expose embedding or vector
• Reconstruct file groupings from a path-like column or from the chunk table itself

That makes the viewer usable for adjacent SQLite-backed vector stores such as NullClaw- or ZeroClaw-style databases, as long as they expose chunk text and embeddings in a reasonably conventional schema.

Rust dependencies

These are declared in Cargo.toml:

• anyhow
• chrono
• gtk4
• rfd
• rusqlite with bundled
• serde
• serde_json

System dependencies

Required

• Rust toolchain with cargo
• GTK 4 development files and runtime
• pkg-config
• C/C++ build tooling appropriate for your platform

WSL / Ubuntu packages

If you are building in WSL on an Ubuntu-like distro, install:

sudo apt update
sudo apt install -y build-essential pkg-config libgtk-4-dev

Windows native build

If you are building natively on Windows instead of WSL, you need:

• Visual Studio Build Tools with the MSVC C++ toolchain
• GTK 4 SDK/runtime
• pkg-config configured to find the GTK installation

The project compiles more reliably in WSL than in a partially configured native Windows environment.

How to compile

WSL

cd /mnt/c/Users/Trude/Desktop/vector_explorer
cargo build

For an optimized build:

cd /mnt/c/Users/Trude/Desktop/vector_explorer
cargo build --release

Windows native

cd C:\Users\Trude\Desktop\vector_explorer
cargo build

For an optimized build:

cd C:\Users\Trude\Desktop\vector_explorer
cargo build --release

How to run

WSL

cd /mnt/c/Users/Trude/Desktop/vector_explorer
cargo run -- main.sqlite

To open a different database:

cd /mnt/c/Users/Trude/Desktop/vector_explorer
cargo run -- /path/to/other.sqlite

Windows native

cd C:\Users\Trude\Desktop\vector_explorer
cargo run -- .\main.sqlite

Notes for WSL graphics

• The app is GTK-based and needs a working GUI/display path in WSL.
• If WSLg or X/Wayland forwarding is not available, the binary can compile successfully but fail to open a display at runtime.
• The app forces GSK_RENDERER=cairo by default to avoid flaky EGL/Zink GPU paths commonly seen on WSL.

Development workflow

Useful commands:

cargo fmt
cargo check
cargo build

Repository contents

• src/main.rs: GTK application and UI behavior
• src/store.rs: SQLite schema detection and adapter loading
• src/projection.rs: embedding projection for the semantic map
• main.sqlite: sample OpenClaw-style memory database