Gigabrain

Gigabrain

A local memory control plane for the agents you already use.

Configuration · Changelog · Contributing · Security · Discussions

Codex, Claude Code, Cursor, and OpenClaw now have useful native memory. That is good. It also means one project can accumulate several machine-local stores with different scopes, retention rules, provenance, and ideas about what is current.

Gigabrain adds a neutral layer above those stores. It imports supported local memories read-only, keeps a provenance ledger, de-duplicates claims, surfaces contradictions, suppresses superseded facts, and exposes one auditable recall interface over MCP and CLI.

It is designed for the gap between products and machines: native memory remains the fast, product-specific layer; Gigabrain is the portable governance and continuity layer you control.

What it does

• Shared recall, explicit scope — project facts and stable user preferences can be shared by Codex, Claude Code, Hermes, and OpenClaw when they point at the same Gigabrain config.
• Provenance for every claim — source host, source path, trust tier, evidence, timestamps, and status stay inspectable.
• Contradiction handling — competing claims are resolved by a deterministic trust → corroboration → recency policy, with an append-only adjudication record.
• Bi-temporal memory — a fact can have both a content time and a validity window; expired and superseded rows are excluded from normal recall.
• Recovery and audit — optional transcript harvesting, secret-risk filtering, review queues, Handoff Records, and a human-readable memory wiki.
• Local-first operation — SQLite, lexical recall, policy checks, and the default setup work without a cloud memory backend.

Gigabrain does not scrape account-level memories from ChatGPT, Claude.ai, Gemini, or Copilot. It does not silently synchronize two computers. It does not turn memory into an unquestionable source of truth. It gives you an inspectable system for deciding what should be recalled and why.

How it works

1. Ingest supported local memory files, explicit checkpoints, and manual exports into a local event store.
2. Project the latest state into SQLite, preserving source and validity metadata.
3. Arbitrate duplicates and contradictions with reviewable rules; destructive uncertainty goes to a queue.
4. Recall through MCP, CLI, or authenticated HTTP with lexical search and optional loopback-only Ollama embeddings.

   Codex   Claude   Cursor   OpenClaw   Hermes   manual exports
     └────────┴────────┴─────────┴─────────┴──────────────┘
                              │   (supported imports are read-only)
                              ▼
                    ┌────────────────────┐
                    │      Gigabrain     │   capture · arbitrate · recall
                    │ arbitration ledger │   MCP · CLI · HTTP
                    └─────────┬──────────┘
                              │  de-conflicted, source-stamped recall
                              ▼
                  any configured agent, via gigabrain_recall

Quickstart

npm install @legendaryvibecoder/gigabrain
npx gigabrainctl init --project-root /path/to/repo
npx gigabrainctl doctor --config ~/.gigabrain/config.json --target both
npx gigabrainctl handoff --config ~/.gigabrain/config.json \
  --output-dir ./gigabrain-memory-audit

init writes the canonical standalone config to ~/.gigabrain/config.json. Use that same config for later commands and MCP registrations. Setup can discover supported local memory files and import them read-only; review the generated audit before enabling broader capture.

Choose the host guide: Codex · Claude Code · OpenClaw.

Two computers are two stores unless you connect them

Installing the same package version on a MacBook and a Mac Studio does not make their memories identical. Code parity, config parity, and data parity are separate checks. Use a reviewed export-bundle / import-bundle workflow or configure the optional authenticated remote bridge; Gigabrain never enables cross-host transport silently. See sharing.

Release highlights

The cloud-inbox drop folder, transcript harvesting, git wiki, Obsidian reference corpus, remote bridge, and URL importer are opt-in. Review configuration and the privacy model before enabling additional data sources or networked providers.

Supported clients

Privacy model

• The default standalone store is local SQLite under ~/.gigabrain/; no hosted Gigabrain backend is required.
• The default LLM provider is none. Optional semantic embeddings are sent only to a loopback Ollama endpoint.
• Raw transcript extraction is permitted only with a local provider or an explicitly injected local hook. Cloud audit review skips credential-risk rows, masks supported PII shapes locally, and omits the original scope; cloud providers do not receive raw transcripts through capture.
• Native host stores are imported read-only. Account-level cloud memories are outside scope unless you export them explicitly.
• Network features are explicit: the remote bridge is opt-in; the Python console's URL import is disabled by default and requires an exact host allowlist.
• The release gate scans tracked and untracked publishable files, npm package contents, Git metadata, and GitHub metadata without printing matched values.

Local-first does not mean risk-free: the SQLite store and generated Markdown can contain sensitive memory. Protect the host account, use disk encryption, restrict file permissions, and review exports before moving them. Full boundary: docs/public/privacy-model.md.

How it works under the hood

Conversation (OpenClaw / Codex / Claude Code / Claude Desktop)
               │
               ▼
┌──────────────────────────────────┐
│           Gigabrain              │
│   (memory layer + MCP server)   │
├──────────────────────────────────┤
│  Capture ─► Policy ─► Registry  │
│  Recall  ◄─ Orchestrator        │
│  Host Sync ◄─ Codex/Claude/etc. │  ← read-only adapters
│  Transcript Harvester ◄─ logs   │  ← optional recovery
│  Arbiter (trust>support>recency)│  ← at ingest + nightly
│  World Model (entities/beliefs) │
│  Git Wiki ◄─► reviewed edits    │  ← optional, high trust
└──────────────┬───────────────────┘
               │
         SQLite + FTS5 + optional local embeddings

• Capture — explicit remember calls, checkpoints, host imports, and optional transcript recovery become append-only events.
• Recall — FTS5/BM25 works without a model. When local embeddings are available, Gigabrain fuses lexical and dense rankings, then applies scope, status, answer-shape, provenance, and arbitration policy.
• Arbitration — a claim-slot world model records competing beliefs and applies trust tier → corroboration → recency with clock-skew and source-independence defenses.
• Audit + Handoff Records — static Markdown/HTML/JSON reports show readiness, source coverage, contradictions, stale rows, and secret-risk omissions.

Gigabrain does not claim state of the art. The published evidence is a small development regression set, not a held-out industry benchmark; see benchmark evidence.

Why use it when native memory exists?

Native memory is now real and useful: Codex has local memories, Claude Code has auto memory, Cursor has project-scoped memories, and OpenClaw has hybrid memory search. Their documented boundaries differ, and several stores remain machine- or product-local.

Gigabrain's job is not to pretend those features do not exist. Its job is to provide cross-product provenance, explicit project/user scopes, deterministic contradiction handling, bi-temporal validity, portable exports, and one protocol surface that you can audit independently. See the detailed comparison.

MCP tools

gigabrain_recall · gigabrain_remember · gigabrain_checkpoint · gigabrain_provenance · gigabrain_recent · gigabrain_sources · gigabrain_sync_status · gigabrain_export_brief · gigabrain_entity · gigabrain_relationships · gigabrain_contradictions · gigabrain_arbitrate · gigabrain_adjudications · gigabrain_beliefs_as_of · gigabrain_review_queue · gigabrain_doctor

The core memory surfaces are mapped across agents (MCP), operators (CLI), and the optional HTTP app — see the coverage matrix for the exact coverage of each action.

CLI

npx gigabrainctl init                       # auto-detect + wire installed agents
npx gigabrainctl handoff --output-dir ./out # Memory Audit + safe Handoff Records
npx gigabrainctl nightly                     # full nightly pipeline (ingest, arbitrate, audit)
npx gigabrainctl doctor                      # health check
npx gigabrainctl inventory                   # memory stats
npx gigabrainctl review contradictions       # inspect cross-agent contradictions
npx gigabrainctl sync-hosts --host codex,claude_code  # force a host re-ingest
npx gigabrainctl vault sync|status           # read-only Obsidian reference corpus
npx gigabrainctl transcript sync|status      # raw-rollout harvester
npx gigabrainctl wiki project|reconcile|status  # git-versioned memory wiki
npx gigabrainctl watch --install-hook --kind=session  # auto-capture on session end
npx gigabrainctl export-bundle --out ./memory-bundle.json
npx gigabrainctl import-bundle --in ./memory-bundle.json
npx gigabrainctl migrate legacy-drop --dry-run  # containment-gated legacy cleanup

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

HTTP endpoints

/gb and /gb/health expose only landing/health information. Data routes accept X-GB-Token, X-OpenClaw-Token, or a Bearer token and fail closed when no token is configured. GB_ALLOW_NO_AUTH=1 is an explicit, dangerous development escape hatch: it bypasses the Node route checks only when no token is configured, emits a warning, and must never be used beyond a loopback-only disposable environment. OpenClaw gateway authentication can still add an outer auth layer.

Key subsystems

Prerequisites

• Node.js >= 22.18.0 (uses node:sqlite and built-in TypeScript type stripping)
• Ollama (optional, for local fact extraction + semantic search)
• OpenClaw >= 2026.2.15 (only for the plugin path)
• Python >= 3.10 (only for the optional web console)

Testing

node tests/run-all.js     # repository suite
node scripts/package-smoke.js  # packaged runtime smoke test
npm run pack:dry-run     # verify published package contents
node scripts/check-no-pii.mjs
node scripts/check-public-mirror.mjs --require-single-commit  # public mirror only
npm run audit:github-metadata -- --repo owner/repository     # after remote creation

Security

• By default, all data-bearing Node HTTP endpoints require timing-safe token auth. The Node token grants access to that configured store; scope is a recall/query filter there, while scoped-token isolation and id-existence concealment are enforced by the optional FastAPI console. The development-only GB_ALLOW_NO_AUTH=1 escape hatch above is unsafe for network exposure.
• The optional web console is documented for loopback binding, adds security headers, bounds uploads and extracted PDF text, and disables URL import by default.
• Release dependencies are checked with npm audit and pip-audit; the dated result and residual risks are in the security review.
• The public mirror is created from an explicit allowlist as a new single-commit history; the private engineering repository is never flipped public in place.

Do not open public issues for vulnerabilities — use the private flow in SECURITY.md.

Contributing

External contributions are welcome. Read CONTRIBUTING.md first. Open Issues for concrete bugs, Discussions for design/usage. Never post secrets, private paths, or runtime artifacts.

License

MIT License. See LICENSE.