GraphPalace

A Stigmergic Memory Palace Engine for AI Agents

GraphPalace is an embedded graph database that makes the memory palace metaphor computationally real. Built as a Rust extension to Kùzu — a property graph database with Cypher, native HNSW vector search, full-text search, and WASM bindings — it adds stigmergic navigation, spatial hierarchy, semantic A* pathfinding, and Active Inference agents. The result: a fully local, private, self-optimizing AI memory system that runs in a browser tab, on a server, or on an edge device. No cloud. No API keys. No data exfiltration.

Status: All 10 phases complete — 13 Rust crates, 694 tests, 24,070 LOC, zero failures. Production-ready with HNSW vector index, full CLI, MCP auth, and crash-safe persistence. Read the paper →

What Makes It Different

System	Storage	Retrieval	Intelligence	Runs Where	Cost
MemPalace	ChromaDB (flat vectors)	Cosine similarity + metadata filter	None (passive)	Local Python	Free
Mem0	LLM-extracted facts	LLM retrieval	LLM-dependent	Cloud	$19–249/mo
Zep/Graphiti	Neo4j (graph)	Graph traversal	Entity resolution	Cloud	$25+/mo
GraphPalace	Property graph + vectors + FTS	*Stigmergic A (semantic + pheromone + structural)**	Active Inference agents	Browser / Edge / Server (WASM)	Free

Key advantages:

🧠 Verbatim storage — drawers hold original text, never summarized (MemPalace's key insight: 96.6% recall)
🐜 Self-optimizing — pheromone trails evolve from usage patterns, no retraining needed
🔍 Semantic A* — finds knowledge through meaning + collective intelligence + graph structure
⚡ HNSW vector index — approximate nearest neighbor search replaces linear scan for sub-millisecond retrieval at scale
🤖 Active Inference agents — autonomous exploration driven by Expected Free Energy minimization
🌐 Runs anywhere — native binary, WASM in browser, Python binding, Node.js — all from one codebase
🔒 Fully local — zero network calls, zero telemetry, your data stays yours

📄 Research Paper

"GraphPalace: A Stigmergic Memory Palace Engine for AI Agents" — 18-page paper with full methodology, algorithms, and experimental evaluation.

Key Findings

Metric	Result	Target	Verdict
Recall@10 (TF-IDF, 500 drawers)	96%	96.6% (MemPalace)	✅ Matches target
*Same-wing A success**	100%	90.9% (STAN_X)	✅ Exceeds by 9.1 pts
*Cross-wing A success**	100%	90.9% (STAN_X)	✅ Exceeds by 9.1 pts
*A latency (same-wing)**	8–21 µs	<200 ms	✅ 10,000× faster
*A latency (cross-wing)**	5–13 µs	<500 ms	✅ 38,000× faster
Insert throughput	32K–50K ops/sec	—	✅ Excellent
Search throughput (100 drawers)	14,948 qps	<50 ms	✅ 0.067 ms/query
Pheromone decay (100 drawers)	108,915 cycles/sec	<500 ms	✅ 9 µs/cycle

The paper reports results from the gp-bench benchmark suite run on release builds. The TF-IDF embedding engine (pure Rust, no model files) achieves recall comparable to MemPalace's all-MiniLM-L6-v2 transformer embeddings. A* pathfinding through the palace hierarchy achieves 100% success for structured queries at microsecond latencies — over 10,000× faster than the original STAN_X implementation.

Soak test: 500 swarm cycles × 5 Active Inference agents (Explorer, Exploiter, Balanced, Specialist, Generalist) = 2,500 actions with 100% agent productivity, validating stable pheromone dynamics and convergence detection.

📥 Download the paper (PDF) · View LaTeX source

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                    gp-bench (Benchmarks)                              │
│       Recall · Pathfinding · Throughput · Comparison Reports         │
├──────────────────────────────────────────────────────────────────────┤
│                    gp-palace (Orchestrator)                           │
│     GraphPalace struct · Search · Navigate · Export/Import           │
├──────────────────────────────────────────────────────────────────────┤
│                     MCP Server (gp-mcp)                              │
│              28 tools · JSON-RPC 2.0 · PALACE_PROTOCOL               │
├──────────┬─────────────┬──────────────┬───────────┬─────────────────┤
│ gp-core  │gp-stigmergy │gp-pathfinding│ gp-agents │ gp-embeddings   │
│  Types   │ 5 Pheromone │  Semantic    │  Active   │  TF-IDF (96%)   │
│  Schema  │   Types     │    A*        │ Inference │  ONNX auto-dl   │
│  Config  │  Decay +    │  Composite   │  Bayesian │  384-dim vecs   │
│  Errors  │  Cypher     │  Cost Model  │  Beliefs  │  Cosine sim     │
├──────────┴─────────────┴──────────────┴───────────┴─────────────────┤
│                        gp-swarm                                      │
│     SwarmCoordinator · ConvergenceDetector · InterestScore           │
├──────────────────────────────────────────────────────────────────────┤
│                       gp-storage (FFI)                               │
│  StorageBackend trait · InMemoryBackend · HNSW Index · KuzuBackend   │
├──────────────────────────────────────────────────────────────────────┤
│                        gp-wasm                                       │
│     InMemoryPalace · JS API · Web Workers · IndexedDB/OPFS          │
├──────────────────────────────────────────────────────────────────────┤
│                  Kùzu Graph Database (C++20)                         │
│         Cypher · HNSW Vector Index · FTS · ACID · WASM               │
└──────────────────────────────────────────────────────────────────────┘

The Palace

Palace
 └── Wing (domain: "project", "person", "topic")
      ├── Room (subject within the wing)
      │    ├── ──HALL──→ Room (same-wing corridor)
      │    ├── ──TUNNEL──→ Room (cross-wing passage — different domain, same topic)
      │    └── Closet (topic summary)
      │         └── Drawer (verbatim memory — NEVER summarized)
      │              └── ──REFERENCES──→ Entity (knowledge graph)
      └── ...more rooms

Every node carries exploitation and exploration pheromones. Every edge carries success, traversal, and recency pheromones. These trails — deposited by past searches and decayed over time — create an adaptive landscape that guides future navigation, just like ants finding the shortest path to food.

Quick Start

Build & Test

git clone https://github.com/web3guru888/GraphPalace.git
cd GraphPalace/rust
cargo build --release
cargo test --workspace    # 694 tests, 0 failures

WASM Bundle (for browser)

cd rust/gp-wasm
wasm-pack build --target web --release
# Output: pkg/graphpalace_bg.wasm + pkg/graphpalace.js

Use as a Library

use gp_core::types::*;
use gp_core::config::GraphPalaceConfig;
use gp_stigmergy::pheromones::PheromoneManager;
use gp_pathfinding::astar::SemanticAStar;
use gp_agents::active_inference::ActiveInferenceAgent;

// Create a palace node
let wing = Wing {
    id: "wing-projects".into(),
    name: "Projects".into(),
    wing_type: WingType::Project,
    embedding: [0.0; 384],
    exploitation_pheromone: 0.0,
    exploration_pheromone: 0.0,
    ..Default::default()
};

// Configure A* pathfinding
let config = GraphPalaceConfig::default();
let astar = SemanticAStar::new(config.astar.clone());

// Create an Active Inference agent
let agent = ActiveInferenceAgent::new(
    "explorer-1".into(),
    "Explorer".into(),
    [0.1; 384],  // goal embedding
    1.0,         // temperature (Explorer archetype)
);

CLI

The graphpalace CLI is fully operational — every command is wired to the real GraphPalace API.

# Install
cargo install --path rust/gp-cli

# Initialize a palace (downloads ONNX model on first run)
graphpalace init --name "My Palace"

# Store a memory
graphpalace add-drawer -c "Rust's borrow checker prevents data races at compile time" \
  -w knowledge -r rust

# Semantic search
graphpalace search "memory safety" -k 5

# Knowledge graph
graphpalace kg add "Rust" "guarantees" "memory safety" --confidence 0.95
graphpalace kg query "Rust"

# Navigate between rooms via A*
graphpalace navigate room_1 room_5

# Palace status
graphpalace status --verbose

# Start MCP server (for AI agent integration)
graphpalace serve
graphpalace serve --token "my-secret"  # with bearer auth

# Export / import
graphpalace export -o backup.json
graphpalace import backup.json --mode merge

Teach Your LLM

Drop skills/graphpalace.md into your LLM's context. It teaches any AI agent how to navigate the palace — Cypher patterns, pheromone semantics, and all 28 MCP tools.

Crate Map

GraphPalace is organized as a Rust workspace with 11 library crates + 1 CLI binary + 1 Python binding:

Crate	Tests	LOC	Description
gp-core	19	1,142	Foundation: palace types (`Wing`, `Room`, `Closet`, `Drawer`, `Entity`, `Agent`), graph schema (Cypher DDL), configuration, error handling
gp-stigmergy	95	1,839	5-type pheromone system: exponential decay, position-weighted path rewards, edge cost recomputation, Cypher query generation (10 query types)
gp-pathfinding	50	1,556	Semantic A* with composite cost model (40% semantic + 30% pheromone + 30% structural), adaptive heuristic, provenance tracking, benchmark infrastructure
gp-agents	50	1,160	Active Inference: EFE minimization, Bayesian belief updates, softmax action selection, temperature annealing (linear/exponential/cosine), 5 archetypes
gp-swarm	50	1,228	Multi-agent coordination: sense→decide→act→update cycle, 3-criteria convergence detection, interest scoring, periodic decay scheduling
gp-embeddings	60	2,153	Embedding engine: TF-IDF (96% recall, pure Rust), ONNX with auto-download from HuggingFace, Mock. Cosine similarity, top-k search, LRU cache
gp-storage	88	3,832	Storage backend: `StorageBackend` trait, `InMemoryBackend` (full CRUD + search), HNSW vector index (M=16, ef=200), Kuzu C API FFI (feature-gated), agent CRUD, diary, contradiction detection
gp-palace	80	2,577	Unified orchestrator: `GraphPalace` struct, auto-hierarchy creation, search with pheromone boosting, A* navigation, KG CRUD with confidence scores, auto-tunnels, auto-entity extraction, export/import
gp-mcp	84	2,165	MCP server: JSON-RPC 2.0 message handling, 28 tool definitions with schemas, PALACE_PROTOCOL prompt generation, bearer token auth
gp-wasm	67	1,859	WASM target: `InMemoryPalace` engine, `wasm-bindgen` JS API, Web Worker message types, IndexedDB/OPFS persistence layer
gp-bench	51	3,008	Benchmark suite: recall@k (target ≥96.6%), A* pathfinding (target ≥90.9%), throughput, ONNX evaluation, Criterion harness, comparison reports
gp-cli	—	1,404	Full CLI: `init`, `search`, `navigate`, `add-drawer`, `status`, `export`, `import`, `serve` (MCP), `kg` subcommands, `agent` management, TOML config
gp-python	—	147	Python bindings stub via PyO3 + maturin: `Palace` class with `add_drawer()`, `search()`, `navigate()`

Total: 694 tests · 24,070 LOC · 0 failures · 0 clippy warnings

Key Algorithms

🐜 Stigmergy — Pheromone System

Five pheromone types create a self-organizing knowledge landscape:

Type	On	Signal	Decay Rate (ρ)	Half-life
Exploitation	Nodes	"This location is valuable — come here"	0.02	~35 cycles
Exploration	Nodes	"Already searched — try elsewhere"	0.05	~14 cycles
Success	Edges	"This connection led to good outcomes"	0.01	~69 cycles
Traversal	Edges	"This path is frequently used"	0.03	~23 cycles
Recency	Edges	"This was used recently"	0.10	~7 cycles

Pheromones are deposited position-weighted along successful paths (earlier edges get larger rewards) and decay exponentially each cycle:

// Deposit: earlier edges in a successful path get larger rewards
let reward = base_reward * (1.0 - position / path_length);

// Decay: exponential with configurable rate per type
let new_value = current * (1.0 - decay_rate);

// Edge cost recomputation after pheromone changes
let pheromone_factor = 0.5 * success.min(1.0) + 0.3 * recency.min(1.0) + 0.2 * traversal.min(1.0);
let cost = base_cost * (1.0 - pheromone_factor * 0.5);

🔍 Semantic A* Pathfinding

A composite edge cost model balances three signals:

cost(edge) = α × C_semantic + β × C_pheromone + γ × C_structural

Weights adapt to the task context:

Context	α (Semantic)	β (Pheromone)	γ (Structural)
Default	0.40	0.30	0.30
Hypothesis Testing	0.30	0.40	0.30
Exploratory Research	0.50	0.20	0.30
Evidence Gathering	0.35	0.35	0.30
Memory Recall	0.50	0.30	0.20

The heuristic adapts based on domain distance — trusts semantics within a wing, weights graph distance across wings.

🤖 Active Inference Agents

Agents minimize Expected Free Energy (EFE) to decide where to look:

EFE(node) = -(epistemic + pragmatic + edge_quality)

Epistemic value — how much will we learn? (1/precision — high uncertainty = high value)
Pragmatic value — how close to our goal? (cosine similarity to goal embedding)
Edge quality — collective intelligence signal (exploitation - exploration pheromones)

Actions selected via softmax policy with temperature-controlled exploration:

Archetype	Temp	Strategy
Explorer	1.0	Pure epistemic — discover new rooms, expand palace frontier
Exploiter	0.1	Follow proven trails, retrieve known memories quickly
Balanced	0.5	Default — mix exploration and exploitation
Specialist	0.3	Manage a specific wing, keep persistent diary
Generalist	0.7	Cross-wing connections, find tunnels between domains

🐝 Swarm Coordination

The SwarmCoordinator runs multi-agent cycles:

Sense — compute frontier with interest scores
Decide — each agent selects action via EFE minimization
Act — agents expand the graph in parallel
Update — deposit pheromones, decay, check convergence

Convergence is declared when ≥2 of 3 criteria are met: growth rate below threshold, pheromone variance stabilized, frontier exhausted.

MCP Tools (28)

GraphPalace exposes a full MCP (Model Context Protocol) server with 28 tools across 6 categories:

Category	Tools	Purpose
Palace Navigation	`palace_status`, `list_wings`, `list_rooms`, `get_taxonomy`, `search`, `navigate`, `find_tunnels`, `graph_stats`	Read and traverse the palace
Palace Operations	`add_drawer`, `delete_drawer`, `add_wing`, `add_room`, `check_duplicate`	Write to the palace
Knowledge Graph	`kg_add`, `kg_query`, `kg_invalidate`, `kg_timeline`, `kg_traverse`, `kg_contradictions`	Entity-relationship triples
Stigmergy	`pheromone_status`, `pheromone_deposit`, `hot_paths`, `cold_spots`, `decay_now`	Pheromone management
Agent Diary	`list_agents`, `diary_write`, `diary_read`	Specialist agent persistence
System	`export`, `import`	Palace portability

The server implements JSON-RPC 2.0 with initialize, tools/list, and tools/call methods. Connect via stdio or HTTP.

When you call palace_status, it returns the PALACE_PROTOCOL — a prompt that teaches any LLM how to use the palace effectively (search before claiming ignorance, navigate to follow connections, deposit pheromones on useful paths, etc.).

Authentication: Set --token <secret> or GRAPHPALACE_TOKEN env var to require bearer token auth for all MCP requests. Unauthenticated requests are rejected with a clear error.

Production Features

These features make GraphPalace reliable for real-world AI agent deployments:

Feature	Description
HNSW Vector Index	Approximate nearest neighbor search (M=16, ef_construction=200, ef_search=50) replaces linear scan. Auto-rebuilds on import. 719 lines in `gp-storage/src/hnsw.rs`.
Crash-Safe Persistence	Atomic file writes via write-to-tmp-then-rename. Config saved alongside palace state on every mutation.
Auto-Tunnels	Cross-wing tunnel edges are built automatically on palace load — rooms with embedding similarity > 0.3 get connected.
Auto-Entity Extraction	Adding a drawer automatically extracts entity names and creates `REFERENCES` edges to the knowledge graph.
HALL + TUNNEL Edges	`add_room` auto-creates HALL edges to existing rooms in the same wing. Tunnels link rooms across wings. Enables full A* pathfinding.
Full TOML Config	Proper `toml` crate parsing for all config sections (palace, pheromones, cost_weights, astar, agents, swarm, cache).
Bearer Token Auth	MCP server supports `--token` flag or `GRAPHPALACE_TOKEN` env var.
ONNX Auto-Download	First `init` automatically downloads all-MiniLM-L6-v2 from HuggingFace. No manual model setup.
KG Contradictions	`kg_contradictions` detects relationships with same subject+predicate but different objects.

Configuration

All parameters are tunable via graphpalace.toml:

[palace]
name = "My Palace"
embedding_model = "all-MiniLM-L6-v2"
embedding_dim = 384

[pheromones.decay_rates]
exploitation = 0.02    # Half-life ~35 cycles
exploration = 0.05     # Half-life ~14 cycles
success = 0.01         # Half-life ~69 cycles
traversal = 0.03       # Half-life ~23 cycles
recency = 0.10         # Half-life ~7 cycles

[cost_weights.default]
semantic = 0.4
pheromone = 0.3
structural = 0.3

[agents]
default_temperature = 0.5
annealing_schedule = "cosine"

[swarm]
num_agents = 5
max_cycles = 1000
decay_interval = 10

[convergence]
history_window = 20
growth_threshold = 5.0
variance_threshold = 0.05
frontier_threshold = 10

See the full file for 200+ configurable parameters across 15 sections.

Skills Protocol

The skills/graphpalace.md file (401 lines) is a standalone document any LLM agent can load to learn palace navigation. It includes:

Core concepts (palace hierarchy, pheromones, A*, agents)
14 Cypher query patterns (semantic search, hierarchy walk, causal chains, contradictions, hot paths, cold spots, ...)
All 28 MCP tool descriptions with usage guidance
7 example workflows (recall, store, navigate, explore, verify, cross-domain, build structure)
Pheromone semantics deep dive
10 key principles for effective palace use

Simply include it in your LLM's system prompt or context window.

Examples

See examples/graphpalace/ for working code:

basic_palace.rs — Create a palace, add wings/rooms/drawers, compute similarity
pheromone_navigation.rs — Deposit pheromones, simulate decay, configure A*
agent_swarm.rs — Create 5 agent archetypes, update beliefs, compute EFE
full_lifecycle.rs — Complete 10-step lifecycle: create → populate → search → navigate → reinforce → decay → export → import → verify
benchmark_run.rs — Generate test palace, run recall/pathfinding/throughput benchmarks, print results

Performance — Measured Results

All benchmarks from gp-bench v0.1.0, release builds on InMemoryBackend. Full methodology in the paper.

Metric	Target	Measured	Status
Recall@10 (TF-IDF)	96.6% (MemPalace)	96–100%	✅ Matches
A* pathfinding (same-wing)	<200 ms	8–21 µs	✅ 10,000× under
A* pathfinding (cross-wing)	<500 ms	5–13 µs	✅ 38,000× under
A* success rate	90.9% (STAN_X)	100% (structured)	✅ Exceeds
Insert throughput	—	32K–50K ops/sec	✅
Search (100 drawers)	<50 ms	0.067 ms (14,948 qps)	✅
Pheromone decay (100 drawers)	<500 ms / 10K edges	9 µs/cycle (109K/sec)	✅
Export (500 drawers)	—	6.8 ms (146/sec)	✅
Soak test (5 agents × 500 cycles)	Stable convergence	100% productivity	✅

Documentation

Guide	Description
Research Paper (PDF)	18-page paper: algorithms, evaluation, 10 equations, 8+ tables, 19 references
Architecture Overview	System layers, all 13 crates, dependency graph, data flow
Storage Backend	`StorageBackend` trait, Kuzu FFI, `InMemoryBackend`, schema init
Palace Orchestrator	`GraphPalace` struct, lifecycle, search, navigation, export/import
Stigmergy System	5 pheromone types, decay formula, deposit operations, emergent behaviors
Pathfinding	Semantic A*, composite cost model, adaptive heuristic, context weights
Active Inference Agents	EFE, Bayesian beliefs, 5 archetypes, swarm coordination, convergence
Benchmarks	Recall, pathfinding, throughput benchmarks, comparison reports
MCP Tools Reference	All 28 tools with parameter tables and PALACE_PROTOCOL
Palace Schema	Full Cypher DDL — 7 node types, 11 edge types, indexes
Skills Protocol	How skills.md works, customization, LLM integration

Research Heritage

GraphPalace stands on the shoulders of:

Contribution	Source	What We Take
Verbatim storage philosophy	MemPalace (Jovovich & Sigman, 2026)	Never summarize; store raw, search semantically. 96.6% LongMemEval recall.
Palace spatial metaphor	Method of Loci (Simonides, ~500 BC)	Wings/Rooms/Halls/Tunnels — 2,500 years of proven spatial memory
Stigmergic coordination	STAN_X v8 (web3guru888, 2026)	5 pheromone types, position-weighted rewards, exponential decay
Semantic A* pathfinding	STAN_X v8	40/30/30 composite cost, adaptive heuristic, context weights
Active Inference agents	Karl Friston (2006+) / STAN_X v8	EFE minimization, Bayesian beliefs, softmax action selection
Embedded graph database	Kùzu (Amine et al., 2023–2025)	Cypher, HNSW vector search, FTS, WASM, columnar storage, MIT license
WASM microservices	WO 2024/239068 A1 (VBRL Holdings)	Modular edge architecture, sandboxed execution
Sentence embeddings	all-MiniLM-L6-v2 (Reimers & Gurevych)	384-dim vectors, proven by both MemPalace and STAN_X
Tool protocol	MCP (Anthropic, 2024)	Standard LLM ↔ tool communication

Roadmap

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Make your changes in the rust/ directory
Run cargo test --workspace && cargo clippy --workspace
Submit a pull request

Please keep PRs focused — one feature or fix per PR.

License

MIT — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 5,257 Commits
.github		.github
benchmark		benchmark
cmake/templates		cmake/templates
dataset		dataset
docs		docs
examples		examples
extension		extension
paper		paper
rust		rust
scripts		scripts
skills		skills
src		src
test		test
third_party		third_party
tools		tools
.clang-format		.clang-format
.clang-tidy		.clang-tidy
.clang-tidy-analyzer		.clang-tidy-analyzer
.gitignore		.gitignore
.lcovrc		.lcovrc
CLA.md		CLA.md
CMakeLists.txt		CMakeLists.txt
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
graphpalace.toml		graphpalace.toml

Folders and files

Latest commit

History

Repository files navigation

GraphPalace

What Makes It Different

📄 Research Paper

Key Findings

Architecture

The Palace

Quick Start

Build & Test

WASM Bundle (for browser)

Use as a Library

CLI

Teach Your LLM

Crate Map

Key Algorithms

🐜 Stigmergy — Pheromone System

🔍 Semantic A* Pathfinding

🤖 Active Inference Agents

🐝 Swarm Coordination

MCP Tools (28)

Production Features

Configuration

Skills Protocol

Examples

Performance — Measured Results

Documentation

Research Heritage

Roadmap

Contributing

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages