Every engineer I know has tried building a "Second Brain." Most of us started with the best of intentions: a folder full of Markdown files in Obsidian, a neat categorization scheme, and a handful of community plugins.

Fast forward six months, and the vault is a graveyard.

Directory indexes fall out of date. Broken links multiply. Then we connect an LLM or AI coding agent to our notes, hoping for leverage—only to discover a worse problem: the agent hallucinates configuration flags, invents internal links to non-existent notes, or silently overwrites curated knowledge with generic corporate boilerplate.

I built (and yes, heavily vibe-coded) Grey Matter to fix this friction. It is an open-source, reproducible second-brain framework designed specifically for humans and AI agents thinking together.

In this setup, Obsidian is the UI—the visual workspace for reading, graph exploration, and manual edits. Antigravity is the AI companion—the autonomous thinking partner that scaffolds notes, triages the inbox, grounds answers in verified facts, and keeps the engine healthy via Model Context Protocol (MCP).

In this post, I will walk you through the core architecture behind Grey Matter, why we separate knowledge content from machinery, and how you can spin up your own seed vault in two minutes.

why agentic note-taking breaks

When you let AI agents read and write directly into a standard Markdown vault, three fundamental failure modes emerge:

  1. Epistemic Blur: The agent treats an unverified, speculative brainstorm draft with the same authoritative weight as a battle-tested post-mortem.

  2. Metadata Drift: Humans hate maintaining YAML frontmatter and directory tables by hand. When agents try to do it without guardrails, they invent arbitrary schemas and break index formats.

  3. Plumbing Bloat: When an AI has to navigate scripts, build hooks, templates, and actual knowledge all in one flat space, its context window gets clogged with mechanics rather than synthesis.

To solve this, Grey Matter combines PARA (4Projects, Areas, Resources, Archive) with the Open Knowledge Format (OKF v0.2), backed by a zero-dependency Python engine.

the two realms

Grey Matter splits the repository into two strictly isolated domains:

├── 00 - Inbox/              # Frictionless capture point for raw notes
├── 01 - Projects/           # Active efforts with deadlines and deliverables
├── 02 - Areas/              # Long-term standards of performance (Finances, Health)
├── 03 - Resources/          # Evergreen reference topics, guides, and architectures
├── 04 - Archive/            # Completed or inactive material preserved for history
├── 05 - Assets/             # Attachments, media, and note templates
│
├── 99 - System/             # Realm 2: Engine, CLI, test suites, hooks, receipts
├── .agents/                 # AI agent personas (Librarian & Technician)
├── AGENTS.md                # Vault Constitution (8 non-negotiable rules)
├── STYLE.md                 # Practitioner writing voice and style guide
└── install.sh               # One-click onboarding script

realm 1: the human knowledge base (00 through 05)

This is where your thoughts, architecture notes, and procedural guides live. It follows strict practitioner voice standards: "Why before how", real operational friction, and concrete verification steps.

realm 2: the machinery (99 - System/)

This is the software engine (brain.py), git hooks, and test suite. Realm 2 is the standard-library Python (>= 3.12) with zero external dependencies. No npm install, no brittle pip wheels. It embeds SQLite FTS5 for sub-millisecond full-text search, BM25 ranking, and cryptographic health attestations. This is also where the agents (AGENTS.md, STYLE.md, etc.) and skills definitions resides.

trust tiers

One of the biggest issues with AI-assisted knowledge management is hallucination creep. In Grey Matter, every note carries an explicit trust tier based on signed verification blocks:

Trust Tier Condition Epistemic Stance

unverified

No verified entries (default for new notes/drafts).

Treat as claims to check rather than established facts.

machine-confirmed

Verified only by an agent:* or process:* actor.

Automated structural and lint checks passed; verify key claims.

human-reviewed

At least one entry signed by human:<owner>.

Ground truth; established personal knowledge.

YAML example in the notes' frontmatter:

verified:
  - by: human:bookian
    date: 2026-09-14

When Antigravity is asked about past infrastructure decisions or personal setup, it doesn’t guess. It calls vault_ground over MCP, inspects the 1-hop graph neighbors, and explicitly cites the trust tier of each source note.

write prose, call tools for everything else

In Grey Matter, humans and agents write prose. Tools handle all structural mutations.

You never manually edit a markdown table in index.md, and you never hand-append an entry to log.md. Hand-crafted index edits are discarded on the next sync, and git pre-commit hooks will abort if indexes drift.

What you want to do What NOT to do What to do instead

Create a new note

Draft raw YAML frontmatter by hand

Ask Antigravity or run brain.py new

Move note out of inbox

Run mv and manually edit two indexes

Ask Antigravity or run brain.py triage

Retire a completed effort

Move folder and edit status manually

Ask Antigravity or run brain.py archive

Record system actions

Manually append lines to log.md

Handled automatically by the engine

Every mutation command supports --dry-run so you (or your agent) can preview changes before touching disk.

the agents

To prevent context bloat, the vault defines two specialized agent personas that Antigravity orchestrates behind the scenes:

  1. The Librarian (librarian): Operates exclusively in Realm 1. It handles note drafting, PARA navigation, graph grounding, and inbox triage in authentic practitioner voice. It has no shell access.

  2. The Technician (technician): Operates exclusively in Realm 2. It runs test suites, zero-dependency audits, git hook verification, and engine refactors.

Antigravity acts as the executive Second Brain—keeping its context window focused on high-level synthesis while dispatching mechanical chores to the specialists.

the daily workflow: obsidian as the ui, antigravity as the companion

Here is how the collaboration works in practice: Obsidian sits open on one screen as your visual interface, while Antigravity runs as your pair programmer and thinking partner.

step 1: conversational capture & scaffolding

Rather than manually creating files and wrestling with frontmatter schemas:

  • Open your Antigravity session and tell it:

    I just finished setting up Tailscale on Proxmox. Let’s write a practitioner how-to guide covering the LXC unprivileged container gotcha.

  • Antigravity calls the vault_scaffold_note MCP tool under the hood, writing the initial note into 00 - Inbox/Setting up Tailscale on Proxmox.md with fully valid OKF v0.2 frontmatter.

  • Because Obsidian watches the filesystem, the note appears immediately in your Obsidian file explorer and graph. You can read, polish, or append screenshots right inside Obsidian.

step 2: triaging with zero index drift

Once the note is ready to be filed into your permanent PARA structure:

  • You don’t drag-and-drop the file or run mv (which would leave stale index tables and broken backlinks).

  • Simply prompt Antigravity:

    Triage the Tailscale note.

  • Antigravity invokes vault_triage via MCP. The engine moves the file to 03 - Resources/, updates the topic frontmatter, regenerates 00 - Inbox/index.md and 03 - Resources/index.md, and appends an entry to log.md.

  • In Obsidian, the note smoothly transitions into its new folder and the index tables refresh in real time.

step 3: grounded recall & graph traversal

When you need to recall past decisions or troubleshoot an incident:

  • Ask Antigravity:

    What was the issue I hit with cgroup delegation when running Kind under rootless Podman?

  • Instead of hallucinating general internet advice, Antigravity invokes vault_ground with the query cgroup delegation podman.

  • Antigravity traverses the 1-hop link graph, reads the note, checks the trust tier (human-reviewed), and summarizes the exact fix while providing Obsidian-clickable links back to the source note.

  • In Obsidian, you can click directly into the referenced note and explore the surrounding local graph.

step 4: deterministic health gates

When wrapping up work or committing changes:

  • Antigravity (or your terminal) runs the automated pre-commit hook:

    ./"99 - System/hooks/pre-commit"

  • The hook verifies note health, synchronizes index tables, runs contract tests, and computes cryptographic attestation receipts. If an agent hallucinated a broken link or an index drifted, the commit is safely blocked.

weekly reviews

As part of the install, there’s also a weekly triage job to maintain the integrity of the brain’s content.

quickstart: spinning up your vault

You can clone the seed repository and set up a healthy vault in about two minutes.

prerequisites

  • Python >= 3.12 (python3 --version)

  • Git

  • Obsidian installed for desktop viewing

  • Antigravity installed as your agent harness

step 1: clone and run installer

Clone the seed repository and run the setup script:

git clone https://github.com/naikoob/grey-matter.git my-brain
cd my-brain
./install.sh

The installer configures git hooks (core.hooksPath = 99 - System/hooks), sets permissions, checks Python compatibility, and verifies the SQLite FTS5 indexing engine.

step 2: open in obsidian and connect antigravity

  1. Obsidian: Select Open folder as vault and choose your my-brain directory.

  2. Antigravity: Open my-brain in Antigravity, Add the grey-matter server to your ~/.gemini/config/mcp_config.json`:

{
  "mcpServers": {
    "grey-matter": {
      "command": "python3",
      "args": ["/path/to/my-brain/99 - System/brain.py", "mcp"]
    }
  }
}

step 3: verify system health

Run the diagnostic doctor:

python3 "99 - System/brain.py" doctor

Expected output:

🩺 Grey Matter Installation Check
================================================================================
Vault root: /path/to/my-brain
--------------------------------------------------------------------------------
✅ Python: 3.13.x at /usr/bin/python3
✅ PARA layout: all 6 directories present
✅ Git repository: /path/to/my-brain
✅ Git hooks path: 99 - System/hooks
✅ Hook: pre-commit: present and executable
✅ Hook: post-edit.py: present and executable
✅ Hook: session-start.py: present and executable
✅ Protocol registration: 1 server(s) declared in .mcp.json
✅ Agent hooks: PostToolUse and SessionStart registered
✅ Weekly timer: enabled and active
✅ Cache directory: /path/to/my-brain/99 - System/.cache
--------------------------------------------------------------------------------
All checks passed (0 warning(s)).
================================================================================

wrapping up

Personal knowledge management shouldn’t require maintaining fragile community plugin stacks or constantly cleaning up after over-enthusiastic AI agents.

By treating Obsidian as the visual UI and Antigravity as the active AI companion—backed by a zero-dependency Python engine with strict pre-commit gates—Grey Matter gives you a second brain that stays clean, searchable, and trustworthy over years of use.

The template seed is open-source under the MIT license:

Clone it, run ./install.sh, open it in Obsidian and Antigravity, and start building your own augmented second brain.