convez.ai
MCP ServerIntegração & APIsAvançado
CadPosting

Third Brain - Memória Semântica Local para Agentes IA

CadPosting/third-brain

Memória compartilhada offline para múltiplos agentes IA com busca híbrida

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece memória semântica compartilhada entre agentes IA (Claude Code, Antigravity, Gemini). Funciona 100% offline com busca híbrida (embedding + BM25), grafo de conhecimento e indexação automática de mudanças em vault local.

Instalação

$npx convez-ai CadPosting/third-brain

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter contexto consistente entre sessões de múltiplos agentes
  • Construir grafo de conhecimento local sem enviar dados à nuvem
  • Implementar recall automático de fatos relevantes antes de respostas

Veredito

Solução madura e well-engineered para agentes que precisam de memória compartilhada sem depender de APIs externas. Stack robusto (LanceDB + BM25 + reranking), arquitetura de serviços com auto-indexação em tempo real, e suporte multiplataforma (Claude Code, Antigravity, Gemini CLI). Exige setup local e conhecimento técnico sólido, mas elimina completamente dependência de cloud.

README

A tradução para o português deste README ainda está na fila.

Third Brain

Local semantic memory server for AI agents. One knowledge base, every agent, zero cloud.

Agents recall relevant notes before every response, write new facts during the session, and summarize what happened at the end — automatically. You never manage the vault yourself.

Works with Claude Code, Antigravity (Gemini, Claude, GPT), and Codex.


How it works

You send a message
        ↓
inject.py searches vault → injects top-3 relevant notes silently into the prompt
        ↓
Agent responds with full memory of past sessions
        ↓
Agent writes new facts/decisions to ~/vault/ via the remember MCP tool
        ↓
watcher.py detects the file change → indexes it within 2 seconds
        ↓
Session ends → summarize.py reads the transcript → writes a session note → indexed
        ↓
Next session, any agent, same shared context

Every agent reads from and writes to the same vault. A decision made in a Claude Code session is available to Antigravity in the next one.


Stack

ComponentRole
bge-small-en-v1.5Local embeddings (~130MB, fully offline)
LanceDBVector store (single file, zero config)
BM25Keyword search alongside vector — catches exact terms vectors miss
RRFFuses vector + keyword rankings before reranking
FlashRank ms-marco-MiniLM-L-12-v2Reranks top-20 results (~4MB)
watchdogAuto-indexes any vault file change within 2 seconds
FastMCP 3.3.1HTTP MCP server all agents connect to
GraphitiKnowledge graph layer (optional — requires Neo4j)

Architecture

Services

Two persistent background services. Install once, they restart automatically.

ServiceWhat it does
third-brain.serviceMCP server on http://127.0.0.1:7891/mcp + /search endpoint
third-brain-watcher.serviceWatches ~/vault/ and re-indexes any .md change within 2s

HTTP endpoints

The server exposes two endpoints:

EndpointProtocolUsed by
POST /mcpMCP over SSEClaude Code, Antigravity, Codex (MCP clients)
POST /searchPlain JSONinject.py hook (fast vault search without SSE handshake)

/search request: {"query": "...", "top_k": 3} /search response: [{"source_path": "...", "text": "..."}, ...]

Claude Code hooks

Three hooks fire automatically on every Claude Code session — no commands needed.

HookEventWhat it does
hooks/inject.pyUserPromptSubmitPOSTs to /search, injects top-3 chunks as additionalContext
hooks/capture.pyPostToolUse (Write/Edit)Re-indexes any .md file the agent just wrote
hooks/summarize.pyStopReads session transcript from transcript_path, writes vault/projects/session-*.md

inject.py: hooks run as short-lived subprocesses. Loading the embedding model in-process takes ~20s and gets dropped by Claude Code's timeout. The hook POSTs to the already-running server's /search endpoint instead (~4-5s warm). The server pre-warms the embedder and reranker on startup.

summarize.py: Claude Code's Stop hook sends {"session_id": "...", "transcript_path": "/path/to/session.jsonl", "cwd": "..."} — it does NOT send transcript content inline. The hook reads the .jsonl file at transcript_path directly.

MCP tools

All agents call these via MCP.

ToolParametersWhat it does
recallquery, top_k, topic_filterHybrid vector+BM25+rerank search. Returns scored results.
remembercontent, title, domain, agent, tagsSaves a note. Auto-creates domain folder + MOC if new.
capturefile_pathRe-indexes a .md file immediately.
summarize_sessionsummary, agent, tagsWrites a session summary to vault/projects/.
list_maptopic (optional)Shows vault folder structure and note counts.
graph_traverseentity, depthTraverses knowledge graph from an entity (requires Neo4j).

Memory protocol (four gates)

Agents follow this on every session. Each gate is a blocking precondition — not a suggestion.

GateWhenAction
GATE 1Before every responserecall with the user's exact message
GATE 2During session, on qualifying eventsremember immediately — never defer
GATE 3After writing any .md filecapture the file path
GATE 4Before ending the sessionsummarize_session

Qualifying events for GATE 2: decision made, bug found and fixed, preference stated, project started or completed, anything worth knowing next session.

For Claude Code: Gates 1, 3, and 4 run automatically via hooks. Gate 2 (remember) must be called by the agent when a qualifying event occurs.

For Antigravity: all four gates are in the skill file (config/antigravity-skill.md) framed as blocking preconditions. The agent must call each tool itself — there are no hooks.


Vault structure

~/vault/                              — fully local, never pushed to git
├── HOME.md                           — vault entry point
├── algorithms/
├── hpc/
│   ├── slurm/
│   └── truba/
│       └── variants/
├── machine-learning/
│   ├── alignment/   (RLHF, PPO, GRPO, DPO)
│   ├── math/
│   └── models/
├── projects/                         — session notes auto-appear here
│   └── session-YYYY-MM-DD_HH-MM.md
└── web-development/
    ├── backend/
    └── frontend/

New domains are created automatically when an agent calls remember with a new domain value. The server creates the folder, a MOC file, and cross-links to related domains.

Open ~/vault/ in Obsidian to browse the full knowledge graph.


Setup

1. Clone and install

git clone https://github.com/CadPosting/third-brain ~/.third-brain
cd ~/.third-brain
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Python 3.10+ required. The venv must live at ~/.third-brain/.venv — service files and hooks reference this path directly.

2. Create your vault

cp -r vault ~/vault

3. Configure environment (optional — knowledge graph layer)

cp .env.example ~/.third-brain/.env
# Set NEO4J_PASSWORD if you have Neo4j running locally
# Leave blank to skip the graph layer — vector + BM25 + reranker still work

4. Install and start the background services

# Copy service files
cp config/third-brain.service ~/.config/systemd/user/
cp config/third-brain-watcher.service ~/.config/systemd/user/

# Enable and start
systemctl --user daemon-reload
systemctl --user enable third-brain third-brain-watcher
systemctl --user start third-brain third-brain-watcher

# Verify
systemctl --user status third-brain
systemctl --user status third-brain-watcher

The server pre-warms the embedder and reranker on startup — first search takes ~4-5s, subsequent calls are similar (CPU inference per query is not cached).

5. Connect Claude Code

⚠️ Prerequisite — check CLAUDE_CONFIG_DIR first. Run echo $CLAUDE_CONFIG_DIR. If it is set, Claude Code reads its config from that directory, not ~/.claude. In every path below, substitute $CLAUDE_CONFIG_DIR for ~/.claude, and note that the MCP registration lives in the mcpServers key of $CLAUDE_CONFIG_DIR/.claude.json — not a separate mcp.json. Configuring ~/.claude/* while CLAUDE_CONFIG_DIR is set is the #1 cause of "the server is running but MCP tools never appear and hooks never fire" — the files exist but Claude Code ignores them. The simplest reliable setup is claude mcp add --scope user --transport http third-brain http://127.0.0.1:7891/mcp, which writes to the correct file automatically regardless of CLAUDE_CONFIG_DIR.

Step 1 — MCP config (~/.claude/mcp.json, or the mcpServers key of $CLAUDE_CONFIG_DIR/.claude.json if that var is set):

cp config/claude-mcp.json ~/.claude/mcp.json

This tells Claude Code to connect to the running server via HTTP. The config uses "type": "http" — do not use "command"/"args" (stdio transport). The server runs HTTP, not stdio. Using the wrong transport causes a silent connection failure where MCP tools never appear in the session.

{
  "mcpServers": {
    "third-brain": {
      "type": "http",
      "url": "http://127.0.0.1:7891/mcp",
      "description": "Third Brain — shared semantic memory for all agents"
    }
  }
}

Step 2 — Hooks (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json if that var is set):

Merge the hooks block from config/claude-settings.json into your existing settings file. Do not replace the whole file — only add the hooks key.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.third-brain/.venv/bin/python ~/.third-brain/hooks/inject.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "~/.third-brain/.venv/bin/python ~/.third-brain/hooks/capture.py" }]
      },
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "~/.third-brain/.venv/bin/python ~/.third-brain/hooks/capture.py" }]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.third-brain/.venv/bin/python ~/.third-brain/hooks/summarize.py"
          }
        ]
      }
    ]
  }
}

Step 3 — CLAUDE.md:

Add memory instructions to ~/.claude/CLAUDE.md telling the agent to call remember with domain and agent="claude-code" on qualifying events. See config/antigravity-skill.md as a template.

Restart Claude Code after making these changes. MCP connections are established at session start.

6. Connect Antigravity

Step 1 — MCP config (~/.gemini/antigravity/mcp_config.json):

Merge the third-brain entry into your existing mcp_config.json under mcpServers:

{
  "third-brain": {
    "serverURL": "http://127.0.0.1:7891/mcp",
    "description": "Third Brain — shared semantic memory."
  }
}

Important: Antigravity requires "serverURL" (camelCase) for HTTP MCP servers — not "url". The wrong key produces a silent connection failure.

Step 2 — Skill:

mkdir -p ~/.gemini/antigravity/skills/third-brain
cp config/antigravity-skill.md ~/.gemini/antigravity/skills/third-brain/third-brain.md

Step 3 — GEMINI.md:

cp config/GEMINI.md ~/GEMINI.md

Antigravity reads ~/GEMINI.md automatically on every session. This file embeds the recall requirement as a top-level instruction so the agent calls recall before every response without needing to be asked. Without this file, the skill exists but is treated as on-demand rather than always-on.

7. Connect Codex

MCP:

cp config/codex-mcp.json ~/.codex/.mcp.json

Skill:

mkdir -p ~/.codex/skills/third-brain
cp config/antigravity-skill.md ~/.codex/skills/third-brain/SKILL.md
sed -i 's/agent="antigravity"/agent="codex"/g' ~/.codex/skills/third-brain/SKILL.md

Verifying it works

# Both services running
systemctl --user is-active third-brain third-brain-watcher

# Server startup log — index loaded cleanly or rebuilt
journalctl --user -u third-brain --no-pager | grep "\[startup\]"
# Expected: "[startup] Index OK." or rebuild ending with "Rebuilt index: N chunks"

# Test the /search endpoint
curl -s http://127.0.0.1:7891/search \
  -X POST -H "Content-Type: application/json" \
  -d '{"query": "test", "top_k": 2}'
# Expected: JSON array (may be empty if vault is new)

After connecting an agent, start a session and send a message. The agent should call recall before responding. After the session ends, check ~/vault/projects/ — a session-YYYY-MM-DD_HH-MM.md file should appear.


Troubleshooting

MCP tools not appearing in Claude Code

Most common cause: wrong transport in ~/.claude/mcp.json. Must use "type": "http" — not "command"/"args". Using command tells Claude Code to spawn a subprocess expecting stdio, but the server speaks HTTP. Connection fails silently and no tools appear. Fix the config and restart Claude Code.

inject.py not injecting context

The hook POSTs to /search on the running server. If no context is injected:

systemctl --user is-active third-brain
curl -s http://127.0.0.1:7891/search -X POST \
  -H "Content-Type: application/json" -d '{"query":"test","top_k":1}'

If the server is down, start it: systemctl --user start third-brain

Session notes not appearing in vault/projects/

The Stop hook reads transcript_path from the payload — a path to the .jsonl session file. Check:

  1. Server is running (summarize.py uses the server's venv for indexing)
  2. ~/vault/projects/ exists
  3. The session had at least 2 user messages (trivial sessions are skipped)

Claude Code stores transcripts at $CLAUDE_CONFIG_DIR/projects/-<cwd-slug>/<session-id>.jsonl (default ~/.claude/projects/). The transcript_path in the hook payload resolves this correctly either way.

LanceDB corruption / "Not Found" errors

The server auto-detects and rebuilds on startup. Check the journal:

journalctl --user -u third-brain --no-pager | grep "\[startup\]"

To force a manual rebuild:

systemctl --user stop third-brain third-brain-watcher
rm -rf ~/.third-brain/lancedb/
systemctl --user start third-brain third-brain-watcher

Always delete the entire lancedb/ directory — never just a subdirectory. Partial deletes leave manifests pointing at missing files.

Antigravity not recalling automatically

Without ~/GEMINI.md, the skill is treated as on-demand. Make sure you ran Step 3 of the Antigravity setup:

cp config/GEMINI.md ~/GEMINI.md

Privacy

Everything stays local. ~/vault/ is in .gitignore — no notes, session summaries, or Obsidian config ever leave the machine. The embeddings model runs locally with no API calls.


Cost

$0. Fully offline.

Ver o original no GitHub

Bom para

Relacionados