@legendaryvibecoder/gigabrain

v0.6.1

Published

9 days ago

Local-first memory layer for OpenClaw, Codex, and Claude — capture, recall, dedupe, audit, native sync

0High
0Medium
0Low

legendaryvibecoder

openclaw memory plugin gigabrain codex claude mcp

Gigabrain

Gigabrain is a local-first memory stack for OpenClaw agents, Codex App, Codex CLI, Claude Code, and Claude Desktop workflows. It converts conversations and native notes into durable, queryable memory, then injects or serves the right context before each prompt so agents stay consistent across sessions.

It is built for local-first production use: SQLite-backed recall, deterministic dedupe/audit flows, native markdown sync, and an optional FastAPI console for memory operations.

Release references:

v0.6.1 release notes: release-notes/v0.6.1.md
v0.6.0 release notes: release-notes/v0.6.0.md
Changelog: CHANGELOG.md
v0.5.3 release notes: release-notes/v0.5.3.md
v0.5.2 release notes: release-notes/v0.5.2.md
v0.5.1 release notes: release-notes/v0.5.1.md

Latest release

v0.6.1 is live.

v0.6.1 is the post-release hardening follow-up to v0.6.0, focused on safer fresh installs, legacy-store upgrades, and tighter scoped recall behavior.
Standalone helper scripts no longer depend on ephemeral ~/.npm/_npx/... cache paths and now degrade cleanly through durable package-spec fallback.
Older native stores now migrate memory_native_chunks safely before scope indexes are built, preventing startup failures on legacy Nimbus and OpenClaw registries.
Deep-audit fixes also harden malformed-config handling, scoped world-model/entity resolution, relation filtering, and partial-cache semantic rerank behavior.

Community thanks across v0.6.0 and v0.6.1:

@unboxed-ai for reporting issues #40, #41, and #42
@vibeputin for PR #33
@Emphasonic for PR #38

Supported clients

| Host surface | Best starting point | What Gigabrain owns | What the host owns | | --- | --- | --- | --- | | OpenClaw | openclaw plugins install @legendaryvibecoder/gigabrain + npm run setup -- --workspace ... | Local registry, native sync, recall orchestration, audit/nightly flows, memory-slot provider | Gateway runtime, channels, agent execution, plugin loading | | Codex App / Codex CLI | npx gigabrain-codex-setup --project-root ... | Shared local project/user memory store, MCP tools, explicit checkpoints, maintenance/doctor flows | App/CLI UX, MCP client wiring, session execution | | Claude Code | npx gigabrain-claude-setup --project-root ... | Shared local project/user memory store, MCP tools, explicit checkpoints, managed .mcp.json wiring | CLAUDE.md loading, project instructions, Claude Code runtime behavior | | Claude Desktop | npm run claude:desktop:bundle for local testing, npm run claude:desktop:bundle:release for portable release assets | Same local MCP-backed memory store and tools as Claude Code | Desktop extension hosting, native app/chat UX, Claude account memory | | Claude Desktop Cowork | Compatibility-audited via the same repo/store | Same local memory layer when pointed at the same repo/config | Cowork orchestration and app control, with no documented memory across sessions |

Quickstart

I use OpenClaw

openclaw plugins install @legendaryvibecoder/gigabrain
cd ~/.openclaw/extensions/gigabrain
npm run setup -- --workspace /path/to/your-openclaw-workspace
npx gigabrainctl doctor --config ~/.openclaw/openclaw.json

Sharing by default: OpenClaw is its own plugin path and does not silently share standalone Codex/Claude memory.

I use Codex

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

Sharing by default: Codex uses the shared standalone store at ~/.gigabrain/config.json on fresh installs and shares memory with Claude only when both point at the same config.

Important: once MCP is registered, use Gigabrain through MCP first. If you ever need a CLI fallback, use the generated helper scripts or npx --yes --package @legendaryvibecoder/gigabrain@<version> ..., not raw node ~/.npm/_npx/.../scripts/gigabrainctl.js cache paths.

I use Claude Code / Claude Desktop

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

Optional Claude Desktop step:

npm run claude:desktop:bundle

Important: run gigabrain-claude-setup first. The desktop bundle points at the standalone config that setup creates. On fresh installs that is usually ~/.gigabrain/config.json; importing the .dxt before setup will fail because that config does not exist yet.

Important: once MCP is registered, use Gigabrain through MCP first. If you need a CLI fallback, use the generated helper scripts or npx --yes --package @legendaryvibecoder/gigabrain@<version> ..., not raw node ~/.npm/_npx/.../scripts/gigabrainctl.js cache paths.

Sharing by default: Claude uses the same shared standalone store as Codex only when both point at the same config. Cowork is compatibility-audited only.

If you need more detail, jump to:

How sharing works

| Mode | Default path | What is shared | What stays isolated | | --- | --- | --- | --- | | OpenClaw plugin | ~/.openclaw/openclaw.json + plugin-managed paths | Nothing automatically with standalone hosts | OpenClaw plugin runtime and memory config | | Codex shared standalone | ~/.gigabrain/config.json | Shared standalone registry + shared user store with Claude when they point at the same config | Repo memory stays separated by project:<repo>:<hash> scope | | Claude shared standalone | ~/.gigabrain/config.json | Same standalone registry + same user store with Codex when they point at the same config | Repo memory stays separated by project:<repo>:<hash> scope | | Project-local standalone | <repo>/.gigabrain/config.json | Nothing outside the repo unless you explicitly reuse that config elsewhere | Repo store and user overlay stay local to that repo |

What it does

Capture: Uses a hybrid memory model where explicit remember intent writes durable memory and Codex App checkpoints write episodic native session logs
Recall: Before each prompt, the recall orchestrator chooses between quick context, entity briefs, timeline briefs, and verification-oriented recall
Standalone MCP: Exposes explicit gigabrain_recall, gigabrain_remember, gigabrain_checkpoint, gigabrain_provenance, gigabrain_recent, gigabrain_doctor, gigabrain_entity, gigabrain_contradictions, and gigabrain_relationships tools for Codex App, Codex CLI, Claude Code, and Claude Desktop
Dedupe: Exact and hybrid semantic deduplication catches duplicates, paraphrases, and malformed near-duplicates with type-aware thresholds
Native sync: Indexes your workspace MEMORY.md and daily notes alongside the registry for unified recall
World model: Projects atomic memories into entities, beliefs, episodes, open loops, contradictions, and syntheses that can power better recall and review
Eval + metrics: Ships an in-process recall eval harness, nightly quality history, and recall latency summaries so recall changes can be measured instead of guessed
Obsidian surface: Builds a structured vault with native files, active memory nodes, entity pages, briefings, reports, and views so your agent can expose memory clearly in Obsidian and sync it to another machine
Person service: Tracks entity mentions across memories for person-aware retrieval ordering
Quality gate: Junk filters, durable-personal retention bias, plausibility heuristics, and optional LLM second opinion keep memory clean without losing important relationship context
Audit: Nightly maintenance with snapshots, execution artifacts, archive reports, review queue retention, and quality scoring
Web console: Optional FastAPI dashboard for browsing, editing, and managing memories

Prerequisites

Node.js >= 22.x (uses node:sqlite experimental API, and Gigabrain now checks this at runtime with a friendly error)
OpenClaw >= 2026.2.15 (gateway + plugin loader, only required for the OpenClaw plugin path)
Python >= 3.10 (only for the optional web console)
Ollama (optional, for local LLM-based extraction review and semantic search)
Obsidian (recommended for the v0.6.x memory surface; core capture/recall still works without it)

Installation

If you are here for Codex App, Codex CLI, Claude Code, or Claude Desktop, skip the OpenClaw setup and jump straight to the standalone options below. OpenClaw is only required for the plugin path.

Option A: OpenClaw npm install + setup wizard (recommended for OpenClaw)

Install:

openclaw plugins install @legendaryvibecoder/gigabrain
cd ~/.openclaw/extensions/gigabrain

Run the one-command setup wizard:

npm run setup -- --workspace /path/to/your-openclaw-workspace

The wizard is safe to rerun. If your OpenClaw config is stale, partial, or comes from older Gigabrain docs, rerun the wizard first and use doctor immediately after.

What the setup wizard does:

Ensures plugins.entries.gigabrain exists in ~/.openclaw/openclaw.json
Sets plugins.slots.memory = "gigabrain" so OpenClaw uses Gigabrain as the active memory provider
Sets runtime paths (workspaceRoot, memoryRoot, outputDir, registryPath)
Enables the v0.6.x hybrid memory defaults for explicit remember intent, native promotion, and world-model-aware surfaces
Bootstraps the DB and indexes native memory files
Enables the Obsidian memory surface by default and builds the first vault unless --skip-vault
Adds or refreshes the AGENTS memory protocol block (unless --skip-agents)
Restarts gateway (unless --skip-restart) and now reports restart failures honestly instead of claiming setup success

Recommended follow-up after setup:

Install Obsidian if you want the v0.6 memory surface.
Open <workspace>/obsidian-vault/Gigabrain.
Start at 00 Home/Home.md.
If the vault looks sparse at first, that is normal: Gigabrain only shows memories that already exist in native notes or the registry.

Verify the install:

npx gigabrainctl doctor --config ~/.openclaw/openclaw.json

Wizard help:

npm run setup -- --help

Useful setup flags:

npm run setup -- --workspace /path/to/workspace --vault-path ~/Documents/gigabrainvault
npm run setup -- --workspace /path/to/workspace --skip-vault

If doctor reports config drift or stale paths, rerun the setup wizard before editing openclaw.json manually.

Option B: OpenClaw manual setup (custom environments)

Install from source:

git clone https://github.com/legendaryvibecoder/gigabrain.git
openclaw plugins install -l /absolute/path/to/gigabrain

{
  "plugins": {
    "slots": {
      "memory": "gigabrain"
    },
    "entries": {
      "gigabrain": {
        "config": {
          "enabled": true
        }
      }
    }
  }
}

plugins.slots.memory = "gigabrain" is the important part that tells OpenClaw to use Gigabrain as the active memory-slot provider.

Notes:

Recent OpenClaw builds discover third-party plugins from ~/.openclaw/extensions or linked paths in plugins.load.paths, not from ~/.openclaw/plugins/node_modules.
Do not add plugins.entries.gigabrain.path manually unless your OpenClaw build explicitly documents that key.

Restart gateway:

openclaw gateway restart

Run migration once:

node scripts/migrate-v3.js --apply --config ~/.openclaw/openclaw.json

Verify the resulting config:

npx gigabrainctl doctor --config ~/.openclaw/openclaw.json

Option C: Codex App + Codex CLI (standalone, no OpenClaw required)

Install Gigabrain into your repo or workspace:

npm install @legendaryvibecoder/gigabrain

Bootstrap Codex wiring for the current repo. Fresh installs use the host-neutral shared standalone store under ~/.gigabrain/, keep the shared personal user store under ~/.gigabrain/profile/, and derive a stable repo-specific scope for the current workspace. If you already have a supported legacy install under ~/.codex/gigabrain/, setup reuses it in place for 0.6.1:

npx gigabrain-codex-setup --project-root /path/to/repo

The Codex setup is safe to rerun and is the recommended repair path for stale standalone configs.

What the Codex setup does:

Creates ~/.gigabrain/config.json for the shared standalone store by default, or reuses ~/.codex/gigabrain/config.json when a legacy standalone install already exists
Bootstraps both the shared standalone store and its shared user store (~/.gigabrain/profile/ on fresh installs), including MEMORY.md, memory/registry.sqlite, and output folders
Adds a Codex-specific AGENTS.md block that prefers Gigabrain MCP tools over ad-hoc file grepping
Creates repo-local .codex/setup.sh plus .codex/actions/ helper scripts for install, verify, maintenance, MCP launch, and manual session checkpointing
Teaches the current repo a stable repo scope so its continuity stays separated inside the shared standalone store by default
Migrates older Codex configs that still have an empty codex.userProfilePath, legacy codex:global project scope defaults, or a recall order that skips the user store
Prints the resolved config path, store root, sharing mode, and whether the path is canonical or legacy-supported
Writes helper scripts that resolve Gigabrain dynamically from repo-local node_modules/.bin, command -v, a package-aware npx fallback, and only stable setup-time source hints instead of depending on an original _npx temp path

What gets shared by default:

Codex and Claude share the same standalone registry only when they point at the same config path.
Repo memory still stays repo-scoped by default through project:<repo>:<hash>.
Personal memory is shared through the user store.
Use --store-mode project-local if you want this repo isolated.
The repo hash is derived from the absolute repo path on this machine. If you move the repo to a different path or another machine, rerun setup or pin codex.projectScope explicitly if you need continuity under the old scope.

Then register the MCP server in Codex:

.codex/actions/install-gigabrain-mcp.sh

Useful Codex commands after setup:

npx gigabrain-codex-setup --project-root /path/to/repo
npx gigabrain-codex-checkpoint --config ~/.gigabrain/config.json --summary "Implemented the MCP server"
npx gigabrainctl doctor --config ~/.gigabrain/config.json --target both
npx gigabrainctl maintain --config ~/.gigabrain/config.json

Standalone Codex defaults in v0.6.0:

llm.provider = "none"
llm.review.enabled = false
vault.enabled = false
codex.projectStorePath = ~/.gigabrain
codex.userProfilePath = ~/.gigabrain/profile
codex.defaultProjectScope = project:<repo>:<hash>
codex.recallOrder = ["project", "user", "remote"]

Codex App behavior in v0.6.0:

Codex App works through MCP, not through undocumented internal Codex state.
gigabrain_remember with target=user is for stable personal preferences and facts that should follow you across repos.
gigabrain_remember with target=project is for repo-specific decisions, conventions, and active project context.
gigabrain_checkpoint is for task-end session capture into ~/.gigabrain/memory/YYYY-MM-DD.md by default on fresh standalone installs.
gigabrain_checkpoint remains repo-scoped by default and uses the derived project:<repo>:<hash> scope for the current workspace.
gigabrainctl maintain is a manual consolidation step when you want promotion and cleanup.
There is no hidden Nimbus-style background logging in Codex App mode.

Recommended Codex install and verify flow:

Run npx gigabrain-codex-setup --project-root /path/to/repo.
Run .codex/actions/install-gigabrain-mcp.sh, or use the printed codex mcp add gigabrain ... command from setup.
Run .codex/actions/verify-gigabrain.sh first. Absolute fallback: npx gigabrainctl doctor --config ~/.gigabrain/config.json --target both.
In Codex, use gigabrain_doctor if you want to confirm that both the repo store and the personal user store are healthy from the MCP side as well.

Upgrading older Codex installs:

Re-run npx gigabrain-codex-setup --project-root /path/to/repo.
The setup rerun preserves existing project memory but migrates stale standalone defaults so the user store is configured, repo scope becomes the default project scope, and recall order becomes project,user,remote.

If you prefer strict per-repo storage, you can opt in explicitly:

npx gigabrain-codex-setup --project-root /path/to/repo --store-mode project-local

That keeps the store under /path/to/repo/.gigabrain/, places the personal user store under /path/to/repo/.gigabrain/profile/, and adds .gigabrain/ to the repo .gitignore.

Troubleshooting:

If gigabrain_doctor or gigabrain_remember target=user reports target store 'user' is not configured, re-run npx gigabrain-codex-setup --project-root /path/to/repo so the standalone config is migrated to the current defaults.
Prefer .codex/actions/verify-gigabrain.sh over memorizing raw paths; it already targets the resolved config for this repo.
If you want to inspect only the user store, run npx gigabrainctl doctor --config ~/.gigabrain/config.json --target user.
If you want to inspect only the repo store, run npx gigabrainctl doctor --config ~/.gigabrain/config.json --target project.

Option D: Claude Code + Claude Desktop (standalone, no OpenClaw required)

Install Gigabrain into your repo or workspace:

npm install @legendaryvibecoder/gigabrain

Bootstrap Claude wiring for the current repo. Fresh installs use the same shared standalone store as Codex under ~/.gigabrain/, keep the shared personal user store under ~/.gigabrain/profile/, and derive the same stable repo-specific scope. If you already have a supported legacy install under ~/.codex/gigabrain/, setup reuses it in place for 0.6.1:

npx gigabrain-claude-setup --project-root /path/to/repo

The Claude setup is safe to rerun. If CLAUDE.md, .mcp.json, or the shared standalone config drift over time, rerun setup first and then run doctor.

What the Claude setup does:

Uses ~/.gigabrain/config.json as the canonical shared standalone config for fresh installs, or reuses ~/.codex/gigabrain/config.json when a legacy standalone install already exists
Bootstraps both the shared standalone store and its shared user store (~/.gigabrain/profile/ on fresh installs), including MEMORY.md, memory/registry.sqlite, and output folders
Adds or refreshes a managed Gigabrain memory block inside CLAUDE.md
Adds or refreshes a gigabrain server entry inside project .mcp.json
Creates repo-local .claude/setup.sh plus .claude/actions/ helper scripts for verify, maintenance, MCP launch, and manual session checkpointing
Preserves existing CLAUDE.md content and unrelated .mcp.json server entries on rerun
Prints the resolved config path, store root, sharing mode, and whether the path is canonical or legacy-supported
Writes helper scripts that resolve Gigabrain dynamically from repo-local node_modules/.bin, command -v, a package-aware npx fallback, and only stable setup-time source hints instead of depending on an original _npx temp path

What gets shared by default:

Claude and Codex share the same standalone registry only when they point at the same config path.
Repo memory still stays repo-scoped by default through project:<repo>:<hash>.
Personal memory is shared through the user store.
Use --store-mode project-local if you want this repo isolated.

Useful Claude commands after setup:

npx gigabrain-claude-setup --project-root /path/to/repo
npx gigabrain-codex-checkpoint --config ~/.gigabrain/config.json --summary "Implemented the Claude workflow"
npx gigabrainctl doctor --config ~/.gigabrain/config.json --target both
npx gigabrainctl maintain --config ~/.gigabrain/config.json
npm run claude:desktop:bundle

Claude Code behavior:

Claude Code reads the local Gigabrain MCP server from .mcp.json
CLAUDE.md teaches Claude how to use gigabrain_recall, gigabrain_remember, gigabrain_checkpoint, and gigabrain_provenance
The Claude path uses the same shared project/user memory model as the Codex standalone path
There is still no hidden background capture; checkpoints stay explicit and task-end driven

Claude Desktop behavior:

npm run claude:desktop:bundle builds a local test .dxt bundle under dist/claude-desktop/ with an absolute config default for the current machine
npm run claude:desktop:bundle:release builds a portable release .dxt bundle with ~/.gigabrain/config.json as the default config path
The bundle wraps the same Gigabrain stdio MCP server used by Claude Code
The desktop extension now launches through a bundled shell launcher that prepends common macOS/Homebrew PATH entries before exec node, instead of assuming Finder can resolve node correctly on its own
The launcher checks common macOS Node manager locations (Homebrew, Volta, ~/.nvm, ~/.fnm, ~/.asdf, ~/.local/bin) and now fails with a clear Node 22+ message instead of silently disconnecting
The desktop extension uses the same Gigabrain MCP server and standalone config contract as Claude Code
For fresh installs, the portable release bundle defaults to ~/.gigabrain/config.json, but that file is created by setup. Run npx gigabrain-claude-setup --project-root /path/to/repo before importing the .dxt.
Existing legacy standalone installs may still resolve to ~/.codex/gigabrain/config.json; if Claude asks for a config path during import, use the resolved path printed by setup rather than guessing.

Claude memory surfaces vs Gigabrain

Claude now has multiple memory/instruction surfaces, and v0.6.0 treats them as complementary rather than interchangeable:

Claude Desktop account/chat memory: Anthropic’s own memory for supported plans and clients. Gigabrain does not read, import, or synchronize those memories.
Claude Code memory: Claude Code loads CLAUDE.md and related local instruction files. Gigabrain integrates with that by managing a Gigabrain block and exposing MCP tools, but it does not replace Claude Code’s own instruction loading.
Claude Desktop Cowork: Anthropic currently documents no memory across Cowork sessions. Gigabrain can still be used as the local memory layer if Cowork is operating in the same repo/config environment, but Cowork itself is not a first-class Gigabrain-native integration in v0.6.0.
Gigabrain: explicit, local-first project/user memory across hosts, with checkpoints, provenance, recall orchestration, maintenance, and a shared local store.

Recommended stance:

Leave Claude native memory on if you want Claude’s own account-level personalization.
Use Gigabrain for durable repo/project continuity, explicit remembered facts, checkpoints, provenance, and shared local stores across Codex/Claude/OpenClaw surfaces.
Do not assume Claude’s native memory and Gigabrain are deduplicated or synchronized with each other.

Recommended Claude install and verify flow:

Run npx gigabrain-claude-setup --project-root /path/to/repo.
Review CLAUDE.md and .mcp.json in the repo.
Run .claude/actions/verify-gigabrain.sh first. Absolute fallback: npx gigabrainctl doctor --config ~/.gigabrain/config.json --target both.
Build the desktop bundle with npm run claude:desktop:bundle for local testing, or npm run claude:desktop:bundle:release for a portable release asset.
If you are upgrading from v0.5.x, rerun the Claude or Codex setup once so the shared user store, helper scripts, launcher wiring, and current standalone defaults are all refreshed together.
In Claude Desktop on macOS, open Settings > Extensions > Advanced settings > Install Extension and import the generated .dxt file.
If Claude asks for a config path, use the resolved path from setup. On fresh installs that is usually ~/.gigabrain/config.json; legacy standalone installs may still use ~/.codex/gigabrain/config.json.
Use .claude/actions/checkpoint-gigabrain-session.sh --summary "..." after meaningful work if you want episodic session capture.

Cowork note:

Cowork is compatibility-audited for the same repo/config path, but v0.6.0 does not claim a dedicated Cowork memory integration.
If you use Cowork and want durable continuity, keep Gigabrain configured in the same repo and rely on the shared local store rather than expecting Cowork session memory.

Upgrade / existing users

OpenClaw users from older Gigabrain docs: move to openclaw plugins install @legendaryvibecoder/gigabrain, rerun npm run setup -- --workspace ..., then run npx gigabrainctl doctor --config ~/.openclaw/openclaw.json.
Codex 0.5.1 / 0.5.2 users: rerun npx gigabrain-codex-setup --project-root /path/to/repo to refresh the shared standalone defaults, verify helper scripts, and doctor path. Existing ~/.codex/gigabrain installs remain supported in place for 0.6.1.
Claude adopters: run npx gigabrain-claude-setup --project-root /path/to/repo, review CLAUDE.md and .mcp.json, then run doctor before building the desktop extension.

Across all hosts, the expected upgrade order is:

Re-run setup for the host surface you use.
Run doctor or the generated verify script.
Only then troubleshoot custom config by hand if something still looks wrong.

Configuration

OpenClaw mode keeps config under plugins.entries.gigabrain.config in openclaw.json. Codex and Claude standalone modes store the same schema in ~/.gigabrain/config.json by default for fresh installs, reuse ~/.codex/gigabrain/config.json when a supported legacy standalone install already exists, or use <repo>/.gigabrain/config.json when you opt into --store-mode project-local. The full OpenClaw plugin schema is defined in openclaw.plugin.json. Key sections:

Runtime

{
  "runtime": {
    "timezone": "Europe/Vienna",
    "paths": {
      "workspaceRoot": "/path/to/agent/workspace",
      "memoryRoot": "memory",
      "registryPath": "/path/to/memory.db"
    }
  }
}

workspaceRoot — agent workspace root (where MEMORY.md lives)
memoryRoot — subdirectory for daily notes (default: memory)
registryPath — path to the SQLite database (auto-created if missing)

Capture

{
  "capture": {
    "enabled": true,
    "requireMemoryNote": true,
    "minConfidence": 0.65,
    "minContentChars": 25,
    "rememberIntent": {
      "enabled": true,
      "phrasesBase": ["remember this", "remember that", "merk dir", "note this", "save this"],
      "writeNative": true,
      "writeRegistry": true
    }
  }
}

requireMemoryNote — when true, only explicit <memory_note> tags trigger capture (recommended)
minConfidence — minimum confidence score to store a memory (0.0–1.0)
rememberIntent — lets the agent treat natural phrases like remember that as an explicit memory-save instruction without exposing the internal <memory_note> protocol to the user

Hybrid capture behavior in v0.6.0:

Explicit durable remember intent writes a concise native note and a matching registry memory when the model emits <memory_note>
Explicit ephemeral remember intent writes to the daily note and stays out of the durable registry by default
Codex App checkpoints write native-only session summaries, decisions, open loops, touched files, and durable candidates into the daily log of the shared standalone store by default
Codex App checkpoints are not background capture; they are intentional task-end summaries that later feed native sync and optional promotion
If the user clearly asked to remember something but the model forgets the internal tag, Gigabrain now queues a review row instead of silently losing the request

Recall

{
  "recall": {
    "topK": 8,
    "minScore": 0.45,
    "maxTokens": 1200,
    "mode": "hybrid"
  }
}

topK — maximum memories injected per prompt
mode — personal_core (identity-heavy), project_context (task-heavy), or hybrid
classBudgets — budget split between core/situational/decisions (must sum to 1.0)

Orchestrator and world model

{
  "orchestrator": {
    "defaultStrategy": "auto",
    "allowDeepLookup": true,
    "deepLookupRequires": ["source_request", "exact_date", "exact_wording", "low_confidence_no_brief"],
    "profileFirst": true,
    "entityLockEnabled": true,
    "strategyRerankEnabled": true
  },
  "worldModel": {
    "enabled": true,
    "entityKinds": ["person", "project", "organization", "place", "topic"],
    "surfaceEntityKinds": ["person", "project", "organization"],
    "topicEntities": {
      "mode": "strict_hidden",
      "exportToSurface": false
    }
  },
  "synthesis": {
    "enabled": true,
    "briefing": {
      "enabled": true,
      "includeSessionPrelude": true
    }
  }
}

The orchestrator chooses a profile-first recall path and only allows deep lookup for source/date/wording verification or true low-confidence-no-brief cases
The world model projects atomic memories into internal entities, beliefs, episodes, contradictions, and syntheses without replacing the underlying registry
Syntheses generate reusable briefs for recall, current state, what changed, and session-start context

Dedupe

{
  "dedupe": {
    "exactEnabled": true,
    "semanticEnabled": true,
    "autoThreshold": 0.92,
    "reviewThreshold": 0.85
  }
}

Above autoThreshold — auto-merged silently
Between reviewThreshold and autoThreshold — queued for review

LLM (optional)

{
  "llm": {
    "provider": "ollama",
    "baseUrl": "http://127.0.0.1:11434",
    "model": "qwen3.5:9b",
    "taskProfiles": {
      "memory_review": {
        "temperature": 0.15,
        "top_p": 0.8,
        "top_k": 20,
        "max_tokens": 180
      },
      "chat_general": {
        "model": "qwen3.5:latest",
        "temperature": 1.0,
        "top_p": 0.95,
        "top_k": 40,
        "max_tokens": 1200,
        "reasoning": "default"
      }
    },
    "review": {
      "enabled": true,
      "profile": "memory_review"
    }
  }
}

Providers: ollama, openai_compatible, openclaw, or none (deterministic-only mode).

Task profiles let you keep one local model family while changing sampling per job. memory_review intentionally uses a small non-zero temperature for stable JSON output with Qwen 3.5, while chat_general stays close to the model defaults.

Native sync

{
  "native": {
    "enabled": true,
    "memoryMdPath": "MEMORY.md",
    "dailyNotesGlob": "memory/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*.md"
  }
}

Indexes workspace markdown files into memory_native_chunks for unified recall alongside the registry.

Architecture note

v0.6 keeps the memory architecture intentionally simple:

native markdown (MEMORY.md, daily notes, curated files) is the human-readable source layer
SQLite is the operational registry, projection, and query layer
FTS5 is an in-database lexical accelerator for active registry recall
there is no separate vector database requirement for core capture, nightly maintenance, or plugin recall

This means changing a local LLM or embedding model does not break the core write/recall path. Optional LLM profiles help with review and extraction quality, but native writes, SQLite indexing, and orchestrated recall still work in deterministic mode.

Native promotion

{
  "nativePromotion": {
    "enabled": true,
    "promoteFromDaily": true,
    "promoteFromMemoryMd": true,
    "minConfidence": 0.72
  }
}

Native promotion turns durable native bullets back into structured registry memories with provenance (source_layer, source_path, source_line). This keeps OpenClaw-style native memory first-class while still giving Gigabrain structured recall, dedupe, and archive behavior.

Obsidian surface (recommended in `v0.6`)

{
  "vault": {
    "enabled": true,
    "path": "obsidian-vault",
    "subdir": "Gigabrain",
    "clean": true,
    "homeNoteName": "Home",
    "exportActiveNodes": false,
    "exportRecentArchivesLimit": 200,
    "manualFolders": ["Inbox", "Manual"],
    "views": { "enabled": true },
    "reports": { "enabled": true }
  }
}

Gigabrain does not require Obsidian for core capture/recall, but you do need Obsidian if you want the visual memory surface introduced in v0.6.x.

The default v0.6.x surface is intentionally curated. When enabled, Gigabrain builds a read-only Obsidian memory surface under <vault.path>/<vault.subdir> with:

00 Home/Home.md
30 Views/Current State.md
30 Views/What Changed.md
30 Views/Important People.md
30 Views/Important Projects.md
30 Views/Native Notes.md
50 Briefings/Session Brief.md

Large diagnostic exports, raw review queues, and broad entity dumps are not part of the default curated surface.

10 Native/ mirrored MEMORY.md, daily/session notes, and curated native files
20 Entities/ people, project, organization, and place pages generated from the world model
20 Nodes/active/ one note per active registry memory with provenance fields like source_layer, source_path, and source_line
30 Views/ dashboards such as Active Memories, Relationships, Review Queue, Recent Archives, Native Sources, Promoted Memories, Registry-only Memories, People, Projects, Open Loops, Contradictions, Current Beliefs, Stale Beliefs, and What Changed
40 Reviews/ generated contradiction/open-loop review artifacts
50 Briefings/ session and nightly briefing notes
60 Reports/ deeper synthesis reports such as contradiction/open-loop summaries
40 Reports/ manifest, freshness, latest nightly/native-sync summaries, and the latest vault build summary

Inbox/ and Manual/ are reserved human-written folders inside the generated subdir and are never cleaned. The surface is intentionally read-only from Obsidian in v0.6.0: the runtime workspace remains the source of truth, and local sync is a one-way pull.

Quickstart:

Run npm run setup -- --workspace /path/to/workspace or enable vault.enabled=true manually.
Open the generated folder <workspace>/obsidian-vault/Gigabrain in Obsidian.
Start in 00 Home/Home.md, then inspect 10 Native/, 20 Entities/, 20 Nodes/active/, 30 Views/, and 50 Briefings/.
On a second machine, use vault pull and open the pulled Gigabrain folder in Obsidian locally.

If you have almost no native notes or remembered facts yet, the initial vault will mostly contain the shell, reports, and empty views. That is expected.

Quality

{
  "quality": {
    "junkFilterEnabled": true,
    "durableEnabled": true,
    "plausibility": {
      "enabled": true
    },
    "valueThresholds": {
      "keep": 0.78,
      "archive": 0.30,
      "reject": 0.18
    }
  }
}

Built-in junk patterns block system prompts, API keys, and benchmark artifacts from being stored. Durable patterns and relationship-aware rules preserve important user, agent, and continuity facts. Plausibility heuristics help archive malformed captures such as broken paraphrases and noisy technical discoveries that should not live as durable memory.

Nightly maintenance

nightly now runs a full maintenance pipeline:

snapshot -> native_sync -> quality_sweep -> exact_dedupe -> semantic_dedupe -> audit_delta -> archive_compression -> vacuum -> metrics_report -> vault_build -> graph_build

Important artifacts written by the run:

output/nightly-execution-YYYY-MM-DD.json
output/memory-kept-YYYY-MM-DD.md
output/memory-archived-or-killed-YYYY-MM-DD.md
output/memory-review-queue.jsonl
output/vault-build-YYYY-MM-DD.md
output/memory-surface-summary.json

The nightly CLI now protects itself with an output-scoped lock, clears stale dead-owner locks, and verifies the execution artifact plus usage log before returning success. If another nightly run is already active, it returns a clean JSON skip instead of overlapping maintenance work.

During nightly maintenance Gigabrain also refreshes the registry FTS5 table after VACUUM, so active-memory lexical recall stays aligned with the current SQLite projection.

See openclaw.plugin.json for the complete schema with all defaults.

First-time setup details

Migration creates the core SQLite schema (memory_events, memory_current, memory_native_chunks, memory_entity_mentions, optional memory_fts, and world-model tables when enabled) and backfills events from any existing data.

A rollback metadata file is written to output/rollback-meta.json in case you need to revert.

Memory notes (how capture works)

Gigabrain captures memories when the agent emits <memory_note> XML tags in its responses. By default, requireMemoryNote is true, so only explicit tags trigger capture — Gigabrain won't silently extract facts from normal conversation.

Tag format

<memory_note type="USER_FACT" confidence="0.9">User prefers dark mode in all editors.</memory_note>

Attributes:

| Attribute | Required | Values | |-----------|----------|--------| | type | Yes | USER_FACT, PREFERENCE, DECISION, ENTITY, EPISODE, AGENT_IDENTITY, CONTEXT | | confidence | No | 0.0–1.0, or high / medium / low (default: 0.65) | | scope | No | Memory scope, e.g. shared, profile:main (default: from config) |

Rules:

One fact per tag — keep it short and concrete
No secrets, credentials, API keys, or tokens
No system prompt wrappers or tool output envelopes
Content must be at least 25 characters (configurable via capture.minContentChars)
Content must not exceed 1200 characters
Nested <memory_note> tags are rejected

Agent instructions (AGENTS.md)

For the agent to emit memory notes correctly, you need instructions in your workspace AGENTS.md (or equivalent instruction file).

If you used the setup wizard, this block is added automatically (unless --skip-agents).
If you used manual setup, add it yourself.

Minimal example:

## Memory

Gigabrain uses a hybrid memory model.

- Native markdown (`MEMORY.md` and `memory/YYYY-MM-DD.md`) is the human-readable layer.
- The Gigabrain registry is the structured recall layer built on top.
- In Codex App and Claude standalone mode, the shared store usually lives under `~/.gigabrain/` on fresh installs, while `~/.codex/gigabrain/` remains supported for legacy setups.
- Use `gigabrain_recall` first for continuity in Codex App sessions, usually with the repo-specific scope your setup generated for this workspace.
- Use `gigabrain_remember` only for explicit durable saves.
- Use `gigabrain_checkpoint` at task end after substantial implementation, debugging, planning, or compaction-style summaries.
- Do not grep Gigabrain store files directly unless the MCP server is unavailable.

### Memory Note Protocol
Gigabrain is native-memory-first. For users, the important behavior is:

- `MEMORY.md` is the curated durable layer
- `memory/YYYY-MM-DD.md` is the daily native layer
- explicit "remember that" moments project into native memory and the structured registry
- Codex App task-end checkpoints project to the daily native layer only
- the user never needs to know the internal XML protocol

Internally, explicit remembers still use `<memory_note>` tags for compatibility and structured capture.

When the user does NOT explicitly ask to save memory:
- Do NOT emit `<memory_note>` tags.
- Normal conversation does not trigger memory capture.

Never include secrets, credentials, tokens, or API keys in memory notes.

How recall works

Before each prompt, Gigabrain:

Sanitizes the user query — strips prior <gigabrain-context> blocks, metadata lines, bootstrap injections, and markdown noise to extract the real question
Entity coreference resolution — detects pronoun follow-ups (e.g. "was weisst du noch über sie?") and enriches the query with the entity from prior messages in the conversation
Uses the recall orchestrator to choose between quick context, entity brief, timeline brief, relationship brief, or verification-oriented recall
Searches the SQLite registry and native markdown files (MEMORY.md, daily notes) for the right supporting context behind that strategy
Recall hygiene — strips persisted recall artifacts and transcript-style control lines out of native recall so old <gigabrain-context>, query:, Source:, or user: / assistant: lines do not feed back into future answers
Entity answer quality scoring — for "who is" / "wer ist" queries, penalizes instruction-like memories ("Add to profile: ...") and boosts direct factual content
Deduplication — removes duplicate memories by normalized content before ranking
Temporal safety — older memories that say today / heute / currently are marked with their recorded date instead of being treated as if they refer to the current day
World-model synthesis — where possible, prefers entity/timeline syntheses over raw snippet piles
Applies class budgets (core / situational / decisions) and token limits
Injects the results as a system message placed before the last user message in the conversation, without exposing internal provenance like file paths or memory ids

The agent doesn't need to do anything special for recall — it happens automatically via the gateway plugin hooks.

If you also use OpenClaw's separate memory_search / memory_get tools, note that their visible Source: behavior is controlled by OpenClaw's own memory.citations setting, not by Gigabrain.

Scope rules

Private/main sessions (direct chat): recall from all sources including MEMORY.md and private scopes
Shared contexts (group chats, other users): only curated shared memories, never private data

Configure scope behavior in openclaw.json under the agent's memory settings.

CLI

The control plane is scripts/gigabrainctl.js:

# Full nightly pipeline (maintain + optional harmonize + audit apply)
node scripts/gigabrainctl.js nightly

# Maintenance only (snapshot, native sync, quality sweep, dedupe, artifacts, vacuum)
node scripts/gigabrainctl.js maintain

# Quality audit (shadow = dry-run, apply = commit changes, restore = rollback, report = render)
node scripts/gigabrainctl.js audit --mode shadow|apply|restore|report

# Print memory inventory stats
node scripts/gigabrainctl.js inventory

# Health check
node scripts/gigabrainctl.js doctor

# Rebuild world-model projections
node scripts/gigabrainctl.js world rebuild --config ~/.openclaw/openclaw.json

# Explain recall strategy selection for a query
node scripts/gigabrainctl.js orchestrator explain --query "Who is Liz?" --config ~/.openclaw/openclaw.json

# Rebuild or inspect synthesis artifacts
node scripts/gigabrainctl.js synthesis build --config ~/.openclaw/openclaw.json
node scripts/gigabrainctl.js synthesis list --config ~/.openclaw/openclaw.json

# Inspect open loops / contradictions
node scripts/gigabrainctl.js review open-loops --config ~/.openclaw/openclaw.json
node scripts/gigabrainctl.js review contradictions --config ~/.openclaw/openclaw.json

# Build the Obsidian memory surface
node scripts/gigabrainctl.js vault build --config ~/.openclaw/openclaw.json

# Inspect freshness and manual-folder health
node scripts/gigabrainctl.js vault doctor --config ~/.openclaw/openclaw.json

# Print the latest surface summary
node scripts/gigabrainctl.js vault report --config ~/.openclaw/openclaw.json

# Pull the generated surface from a remote host to a local vault root
node scripts/gigabrainctl.js vault pull \
  --host memory-host \
  --remote-path /path/to/obsidian-vault \
  --target ~/Documents/gigabrainvault

# Compatibility helper for a direct build
node scripts/vault-export.js --config ~/.openclaw/openclaw.json

nightly --help is safe and prints usage instead of starting a real run.

All commands are also available as npm scripts: npm run setup, npm run nightly, npm run maintain, npm run vault, npm run vault:doctor, npm run vault:report, npm run vault:pull, npm run vault:export, etc.

Practical local-Obsidian flow:

Build or refresh the surface on the runtime machine: npm run vault
Pull it to your laptop: npm run vault:pull -- --host nimbus --remote-path /path/to/obsidian-vault --target ~/Documents/gigabrainvault
Open ~/Documents/gigabrainvault/Gigabrain in Obsidian

HTTP endpoints

The plugin registers these routes on the OpenClaw gateway:

| 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 grouped by claim slot | | GET | /gb/relationships | Token | Stored relationship graph rows with counterpart metadata |

Auth uses the X-GB-Token header. The token is configured in the gateway.

Web console (memory_api)

An optional FastAPI dashboard for browsing and managing memories. See memory_api/README.md for setup.

Features: dual-surface landing view with vault freshness and review/archive summaries, memory browser with search/filter, concept deduplication view, audit queue, document store, profile viewer, and knowledge graph visualization.

Testing

# Run all tests (requires Node.js with --experimental-sqlite)
npm test

# Filter by category
npm run test:unit
npm run test:integration
npm run test:regression
npm run test:performance

The default suite includes dozens of executable tests covering config validation, policy rules, capture service, memory actions, orchestrator behavior, projection store FTS behavior, person service, world-model behavior, BM25 ranking, eval tooling, semantic rerank fallbacks, native-sync query handling, queue/runtime guards, vault surface generation and pull, OpenClaw setup wizard behavior, Codex and Claude standalone setup flows, packaged-install setup smokes, Claude Desktop bundle packaging, audit maintenance, migration, bridge routes, native recall, regression behavior, and nightly performance.

Release validation can go further with:

npm run test:release-live for live Codex CLI registration and live OpenClaw install/setup checks on a machine that has both CLIs installed
npm run eval:deep-recall for the expanded recall-routing evaluation used when the core recall stack changes
node scripts/eval-runner.js --config ~/.openclaw/openclaw.json --mode golden --cases eval/cases.jsonl --out /tmp/gigabrain-eval.json when you want a standalone v0.6.x recall-quality report outside the nightly run

Contributing

External contributions are welcome.

Read CONTRIBUTING.md before opening a PR.
Use Issues for concrete bugs or scoped feature requests.
Use Discussions for design questions, product ideas, or usage help.
Please avoid posting secrets, private paths, or personal runtime artifacts in issues or PRs.

If you want to propose a bigger memory-behavior change, open a discussion first. Small, well-tested PRs are much easier to review.

Benchmarking

# Single benchmark run
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

# Compare two environments
node bench/memorybench/compare.js \
  --base-a http://host-a:18789 --token-a "$TOKEN_A" --label-a baseline \
  --base-b http://host-b:18789 --token-b "$TOKEN_B" --label-b candidate \
  --runs 3

Results are 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 flows
│   ├── maintenance-service.js  # Nightly pipeline, snapshots, execution artifacts
│   ├── llm-router.js           # LLM provider abstraction + task profiles
│   ├── vault-mirror.js         # Obsidian memory surface builder + pull workflow
│   ├── http-routes.js          # Gateway HTTP endpoints
│   ├── review-queue.js         # Capture and audit review queue retention
│   └── 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 helper
│
├── memory_api/                 # Optional web console (FastAPI)
│   ├── app.py
│   ├── requirements.txt
│   └── static/index.html
│
├── tests/                      # Test suite
├── bench/memorybench/          # Benchmark harness
└── eval/                       # Evaluation cases

Security

All HTTP endpoints require token authentication (X-GB-Token header)
Auth is fail-closed: if no token is configured, all requests are rejected
The web console escapes all user content to prevent XSS
The memory_api binds to 127.0.0.1 only — use Tailscale or SSH tunneling for remote access
Dependencies are audited with pip-audit and npm audit. Transitive dependency alerts (e.g. from peer dependencies) are tracked via Dependabot

Please do not open public issues for vulnerabilities. Use the private reporting flow in SECURITY.md.

License

MIT License. See LICENSE file for details.