Full setup guide

Claude Code / Claude Desktop

npm install @legendaryvibecoder/gigabrain
npx gigabrain-claude-setup --project-root /path/to/repo
.claude/actions/verify-gigabrain.sh

Full setup guide

Upgrading? See the upgrade guide.

How it works

Conversation (OpenClaw / Codex / Claude Code / Claude Desktop)
               │
               ▼
┌──────────────────────────────────┐
│           Gigabrain              │
│   (memory layer + MCP server)   │
├──────────────────────────────────┤
│  Capture ─► Policy ─► Registry  │
│  Recall  ◄─ Orchestrator        │
│  Native Sync ◄─► MEMORY.md      │
│  World Model (entities/beliefs) │
│  Vault Mirror ─► Obsidian       │
└──────────────┬───────────────────┘
               │
         SQLite + FTS5

Highlights

• Capture — hybrid model: explicit remember intent writes durable memory, Codex checkpoints write episodic session logs
• Recall — orchestrator chooses between quick context, entity briefs, timeline briefs, and verification-oriented recall automatically
• MCP tools — gigabrain_recall, gigabrain_remember, gigabrain_checkpoint, gigabrain_provenance, gigabrain_recent, gigabrain_doctor, gigabrain_entity, gigabrain_contradictions, gigabrain_relationships
• Dedupe — exact + hybrid semantic deduplication with type-aware thresholds
• Native sync — indexes MEMORY.md and daily notes alongside the registry for unified recall
• World model — entities, beliefs, episodes, open loops, contradictions, and syntheses
• Obsidian surface — structured vault with native files, entity pages, briefings, and views
• Quality gate — junk filters, plausibility heuristics, and LLM second opinion
• Audit — nightly maintenance with snapshots, archive reports, and quality scoring
• Eval — in-process recall eval harness, nightly quality history, and latency summaries
• Web console — optional FastAPI dashboard for browsing and managing memories
• Person service — entity mention tracking for person-aware retrieval ordering

Key subsystems

| Subsystem | Description | Docs | |-----------|-------------|------| | Sharing model | Multi-host sharing modes and scope rules | docs/sharing.md | | Configuration | Full config reference (runtime, capture, recall, dedupe, LLM, vault, quality) | docs/configuration.md | | Memory protocol | Capture tags, agent instructions, AGENTS.md | docs/memory-protocol.md | | Recall pipeline | 11-step orchestrated recall with strategy selection | docs/recall.md | | Obsidian surface | Vault structure, setup, pull workflow | docs/obsidian.md | | Nightly maintenance | Pipeline steps, artifacts, scheduling | docs/maintenance.md |

Prerequisites

• Node.js >= 22.x (uses node:sqlite experimental API)
• OpenClaw >= 2026.2.15 (only for the plugin path)
• Python >= 3.10 (only for the optional web console)
• Ollama (optional, for local LLM review and semantic search)
• Obsidian (recommended for the v0.6.x memory surface)

CLI

npx gigabrainctl nightly                          # Full nightly pipeline
npx gigabrainctl maintain                         # Maintenance only
npx gigabrainctl audit --mode shadow|apply        # Quality audit
npx gigabrainctl inventory                        # Memory stats
npx gigabrainctl doctor                           # Health check
npx gigabrainctl world rebuild                    # Rebuild world model
npx gigabrainctl orchestrator explain --query "…" # Explain recall strategy
npx gigabrainctl synthesis build                  # Rebuild synthesis
npx gigabrainctl review contradictions            # Inspect contradictions
npx gigabrainctl review open-loops                # Inspect open loops
npx gigabrainctl vault build                      # Build Obsidian surface
npx gigabrainctl vault doctor                     # Vault health check
npx gigabrainctl vault report                     # Surface summary
npx gigabrainctl vault pull --host … --target …   # Pull vault to laptop

All commands accept --config <path> and are also available as npm run scripts.

HTTP endpoints

| Method | Path | Auth | Description | |--------|------|------|-------------| | GET | /gb/health | No | Health check | | POST | /gb/recall | Token | Memory recall for a query | | POST | /gb/suggestions | Token | Structured suggestion ingest | | POST | /gb/bench/recall | Token | Recall benchmark endpoint | | GET | /gb/memory/:id/timeline | Token | Event timeline for a memory | | GET | /gb/evolution | Token | Entity evolution timeline by claim slot | | GET | /gb/relationships | Token | Relationship graph with counterpart metadata |

Auth uses the X-GB-Token header. Fail-closed: no token configured = all requests rejected.

Web console

Optional FastAPI dashboard for browsing and managing memories. See memory_api/README.md.

Testing

npm test                    # All tests
npm run test:unit           # Unit tests only
npm run test:integration    # Integration tests
npm run test:regression     # Regression tests
npm run test:performance    # Performance tests
npm run test:release-live   # Live Codex/OpenClaw smoke
npm run eval:deep-recall    # Recall-routing evaluation

Benchmarking

node bench/memorybench/run.js \
  --base-url http://127.0.0.1:18789 \
  --token "$GB_UI_TOKEN" \
  --cases eval/cases.jsonl \
  --topk 8 --runs 3

Results written to bench/memorybench/data/runs/.

Project structure

gigabrain/
├── index.ts                    # Plugin entry point (OpenClaw extension)
├── openclaw.plugin.json        # Config schema definition
├── package.json
│
├── lib/core/                   # Core services
│   ├── config.js               # Config validation and normalization
│   ├── capture-service.js      # Extraction, dedup, registry upsert
│   ├── recall-service.js       # Search, filter, inject pipeline
│   ├── event-store.js          # Append-only event log
│   ├── projection-store.js     # Materialized current-state view
│   ├── native-sync.js          # MEMORY.md + daily notes indexer
│   ├── person-service.js       # Entity mention graph
│   ├── policy.js               # Junk filter, plausibility, retention rules
│   ├── audit-service.js        # Quality scoring, review, restore/report
│   ├── maintenance-service.js  # Nightly pipeline, snapshots, artifacts
│   ├── llm-router.js           # LLM provider abstraction + task profiles
│   ├── vault-mirror.js         # Obsidian surface builder + pull workflow
│   ├── http-routes.js          # Gateway HTTP endpoints
│   ├── review-queue.js         # Capture and audit review queue
│   └── metrics.js              # Telemetry counters
│
├── scripts/                    # CLI tools
│   ├── gigabrainctl.js         # Main control plane
│   ├── migrate-v3.js           # Schema migration
│   ├── harmonize-memory.js     # Memory harmonization
│   └── vault-export.js         # Direct vault surface build
│
├── doc