Your AI agent is smart, but it starts from zero every conversation. A personal knowledge base fixes that — meetings, emails, research, and original ideas flow into a searchable brain that your agent reads before every response and writes to after every interaction. The agent compounds knowledge over time.

GBrain defines how to organize that knowledge. Undisk provides where to store it with safety guarantees. We cloned and adapted GBrain’s organizational pattern into Undisk’s built-in Brain template so teams can apply it in one call. Together, they create a production-grade personal AI brain with undo, audit trails, and multi-agent coordination.

Why Knowledge Bases Need Versioned Storage

Knowledge bases maintained by AI agents face a unique challenge: the agent writes thousands of files autonomously, and mistakes compound silently. A bad entity merge can corrupt hundreds of cross-references. An enrichment pipeline bug can overwrite compiled truth with hallucinated data. Without per-file versioning, recovery means manual reconstruction.

GBrain’s native storage is a Git repository. Git works for human-paced editing, but it has fundamental limitations for AI agent workloads:

  • Granularity mismatch: Git commits bundle multiple file changes. Undoing one file means reverting the entire commit, losing every other change in that batch.
  • No surgical undo: git revert operates on commits, not individual file operations. If an agent modifies 50 entity pages in one enrichment pass and corrupts 3 of them, Git cannot restore just those 3.
  • Merge conflicts: Multiple agents writing to the same brain repository create merge conflicts that require manual resolution.
  • No audit trail: Git log shows who committed, but not which agent instance, which API key, or which session triggered the write.

Undisk solves all of these. Every write_file, create_file, append_log, and delete_file operation creates an immutable version. Any file can be restored to any prior state in under 50ms. The audit trail records every mutation with agent identity, timestamp, and content hash.

The Architecture: Two Complementary MCP Servers

┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Your Agent     │    │   Undisk MCP     │    │   GBrain MCP     │
│                  │    │                  │    │   (optional)     │
│  read brain      │───>│  versioned       │    │                  │
│  write pages     │───>│  file storage    │    │  hybrid search   │
│  search          │───>│  with undo       │    │  (vector +       │
│  checkpoint      │───>│                  │    │   keyword)       │
│  collaborate     │───>│  audit trail     │    │                  │
│  query           │───>│                  │───>│  entity detect   │
│                  │    │  24 MCP tools    │    │  enrichment      │
└──────────────────┘    └──────────────────┘    └──────────────────┘

Undisk handles all file operations — reads, writes, deletes, moves, search, versioning, undo, checkpoints, collaboration locks, secrets, and audit trail. This is the storage layer.

GBrain (optional) adds hybrid search with vector embeddings, entity detection, and enrichment pipelines. GBrain’s gbrain query provides semantic search that goes beyond keyword matching. If you do not need vector search, Undisk’s search_files tool handles regex and substring search across all workspace files.

Setting Up a Brain Workspace

Option 1: Use the Built-in Brain Template

Undisk ships a brain workspace template that scaffolds the full GBrain-recommended directory structure:

Your agent calls:
  workspace_checkpoint(action: "apply_template", template: "brain")

This creates:
  RESOLVER.md          — master decision tree for filing
  schema.md            — page conventions and templates
  people/README.md     — one page per human being
  companies/README.md  — one page per organization
  deals/README.md      — financial transactions
  meetings/README.md   — event records with transcripts
  projects/README.md   — things being actively built
  ideas/README.md      — raw possibilities
  concepts/README.md   — mental models and frameworks
  writing/README.md    — prose artifacts
  sources/README.md    — raw data imports
  inbox/README.md      — unsorted quick captures
  log.md               — chronological operation log

Each README.md is a resolver document that tells your agent exactly what belongs in that directory and what does not. The RESOLVER.md at the root is the primary decision tree — your agent reads it before creating any new page.

Unfolding Brain Into An Existing Workspace

You do not need a fresh workspace. The template is idempotent:

1. workspace_checkpoint(action: "create", name: "pre-brain-unfold")
2. workspace_checkpoint(action: "apply_template", template: "brain")
   -> Created 13 files
3. workspace_checkpoint(action: "apply_template", template: "brain")
   -> Skipped 13 (already exist)

This lets you add Brain structure to a workspace that already contains code, notes, or logs without overwriting those files.

Option 2: Manual Setup

Create the directories and resolver files yourself using create_file. The key files are:

  1. RESOLVER.md — The decision tree. Your agent must read this before filing anything.
  2. schema.md — Page template conventions: compiled truth above the line, timeline below.
  3. Per-directory README.md — Local resolvers with positive definitions and disambiguation rules.

The Brain-Agent Loop on Undisk

The core pattern is simple: read before responding, write after every interaction.

Read Phase

1. Agent receives a question mentioning "Sarah Chen"
2. search_files(pattern: "Sarah Chen") → finds people/sarah-chen.md
3. read_file(path: "people/sarah-chen.md") → compiled truth + timeline
4. Agent responds with full context from the brain

Write Phase

1. Agent learns new information about Sarah during conversation
2. write_file(path: "people/sarah-chen.md") → updates compiled truth
3. append_log(path: "people/sarah-chen.md") → adds timeline entry
4. Both operations create immutable versions automatically

The Undo Safety Net

1. Enrichment pipeline runs overnight, touches 200 entity pages
2. Morning review reveals 3 pages have incorrect data
3. list_versions(path: "people/sarah-chen.md") → see all versions
4. restore_version(path: "people/sarah-chen.md", version_id: "...") → instant fix
5. The other 197 correct updates are untouched

Atomic Checkpoints

1. workspace_checkpoint(action: "create", name: "pre-bulk-import")
2. Agent imports 500 new pages from email archive
3. Something goes wrong — duplicates, bad entity resolution
4. workspace_checkpoint(action: "restore", checkpoint_id: "...")
5. Entire brain rolls back to pre-import state atomically

What Undisk Adds Over Git-Based Brain Storage

CapabilityGitUndisk
Per-file undo❌ Requires full commit revert✅ Any file, any version, <50ms
Tamper-evident audit❌ Rebase rewrites history✅ Hash-chain verified
Multi-agent writes❌ Merge conflicts✅ Immutable versions, no conflicts
Collaboration locks❌ None✅ File locks with auto-expiry
Agent handoff notes❌ None✅ Leave notes for other agents
Atomic checkpoint/restore❌ Branch management✅ Named snapshots, one-call restore
Secret management❌ .gitignore or separate tool✅ Encrypted vault (vault_secret)
Workspace search❌ grep across checkout✅ search_files with regex, case control
Activity context❌ None✅ Recent edits shown with tool responses

Best Practices for Brain Maintenance

  1. Always read RESOLVER.md before creating pages. The resolver prevents duplicate pages and filing ambiguity. Include this rule in your agent’s system prompt.

  2. Use append_log for timeline entries. The timeline section of brain pages is append-only. Use append_log instead of rewriting the entire file — it is faster and creates a cleaner version history.

  3. Checkpoint before bulk operations. Before importing email archives, running enrichment sweeps, or processing meeting transcripts, create a workspace_checkpoint. The cost is negligible; the safety is invaluable.

  4. Use search_files before external APIs. Check the brain first. The answer may already be there, and it will be faster and more contextual than a web search.

  5. Store API keys in vault_secret. Integration credentials (email, calendar, social media APIs) belong in the encrypted vault, not in brain files.

  6. Use collaboration locks for multi-agent brains. If multiple agents write to the same brain, use workspace_collaborate to claim locks on files during enrichment passes.

Getting Started

  1. Create an account at mcp.undisk.app and generate an API key
  2. Initialize the brain — have your agent call workspace_checkpoint with action: "apply_template" and template: "brain"
  3. Start writing — follow the compiled truth + timeline pattern for every entity page
  4. Optionally add GBrain — install gbrain for hybrid search and enrichment pipelines

The brain compounds with every interaction. Start small, let the agent maintain it, and watch it become your most valuable AI infrastructure.

Frequently Asked Questions

What is a personal knowledge base for AI agents?

A structured collection of markdown files — one page per person, company, deal, or idea — that your AI agent reads before responding and writes to after every conversation. The agent maintains cross-references, resolves entities, and keeps compiled summaries current. GBrain calls this pattern a 'brain.'

Why use Undisk instead of Git for brain storage?

Git requires explicit commits and cannot undo a single file write without reverting an entire commit. Undisk versions every individual write automatically in under 50ms. You can surgically restore any file to any prior state without affecting other files. Undisk also provides tamper-evident audit trails, multi-agent collaboration locks, and atomic workspace checkpoints — none of which Git offers natively.

Can I use GBrain and Undisk together?

Yes. They are complementary MCP servers. GBrain provides the knowledge organization conventions, entity detection, enrichment pipelines, and hybrid search (vector + keyword). Undisk provides the versioned storage layer with undo, audit trails, and collaboration primitives. Configure both in your MCP client for the best of both worlds.

What is the MECE directory structure?

MECE stands for Mutually Exclusive, Collectively Exhaustive. Every piece of knowledge lands in exactly one directory — people/, companies/, deals/, meetings/, ideas/, concepts/, writing/, projects/, or inbox/. Each directory has a README.md resolver that defines what goes there and what does not. A top-level RESOLVER.md provides the decision tree for filing new content.

What happens if my agent writes bad data to the brain?

Every write creates an immutable version. Use restore_version to undo any single file change in under 50ms without affecting other files. For bulk operations, create a workspace_checkpoint before starting — you can atomically restore the entire brain to that point if needed.