PBrain

PBrain is a lean local knowledge base for people who want durable memory without running a second-brain lab.

It stores structured notes, decisions, patterns, project context, and distilled session signals in SQLite. It is CLI-first, serverless by default, and designed to sit beside an agent or personal workflow without slowing it down.

PBrain is inspired by Garry Tan's GBrain idea: keep a personal source of truth that an agent can query, update, and reason from. The difference is scope. PBrain keeps the useful part and removes the machinery that makes personal knowledge systems heavy: no graph-first architecture, no always-on service, no mandatory vector store, no review queue, no scoring layer.

What it does

• Stores structured personal knowledge in a local SQLite database.
• Searches entries with SQLite FTS.
• Captures durable context from chat/session logs through a configured distiller.
• Requires source snippets for distilled entries, so generated memories keep provenance.
• Exports readable markdown pages for inspection or backup.
• Offers an optional local HTTP API for lightweight integrations.
• Provides an optional Hermes plugin bridge with explicit tools only.

What it does not do

• It does not dump raw transcripts into memory.
• It does not store secrets.
• It does not run as a server unless you ask it to.
• It does not create candidate/review queues by default.
• It does not use confidence scores, importance scores, fit scores, or ranking theater.
• It does not require embeddings, a vector database, or MCP.

Design principles

PBrain has one job: make useful knowledge retrievable later.

The core rules are simple:

1. Store structured entries, not raw logs.
2. Preserve timestamps and source provenance.
3. Fail closed when automatic distillation is not configured.
4. Keep native agent memory small. Put broader context in PBrain.
5. Prefer boring local tools over complex infrastructure.

Install

PBrain currently uses Python 3.11+ and the standard library at runtime.

git clone https://github.com/<owner>/pbrain.git
cd pbrain
python -m venv .venv
source .venv/bin/activate
pip install -e .

For development:

pip install pytest
python -m pytest tests -q
python scripts/smoke.py

Quick start

pbrain health
pbrain write-entry --kind decision --title "Keep it local" --content "PBrain should stay local and CLI-first."
pbrain search "local CLI"
pbrain context --recent 10
pbrain export

By default, PBrain stores data under its configured home directory. Runtime data is intentionally ignored by git.

Dream-cycle distillation

PBrain can scan session files into a source ledger, then run a configured distiller to turn useful conversation context into structured entries.

pbrain dream scan --sessions-dir /path/to/sessions
pbrain dream due
pbrain dream run --date YYYY-MM-DD --distiller-command "python scripts/gemini_dream_distiller.py"
pbrain dream status
pbrain dream catchup --dry-run

A distiller receives a prompt on stdin and must return JSON like this:

{
  "accepted": [
    {
      "kind": "decision",
      "title": "Keep PBrain lean",
      "content": "PBrain should stay local, structured, and CLI-first.",
      "tags": ["architecture"],
      "source_snippet": "PBrain should stay local, structured, and CLI-first."
    }
  ]
}

Every item must include an exact source_snippet copied from the transcript. If the distiller is missing, fails, or returns ungrounded output, PBrain writes nothing for that session.

The bundled Gemini distiller is optional. It loads API keys from the environment or a local .env file, never from committed project files.

Optional API

The API is off by default.

pbrain serve --host 127.0.0.1 --port 8765
pbrain serve --read-only

Endpoints:

GET  /health
GET  /context?recent=10
GET  /search?q=query
POST /entries

Project layout

pbrain/
  api.py          # optional local HTTP API
  cli.py          # command-line interface
  config.py       # runtime path/config resolution
  dream.py        # session scan + distillation pipeline
  repository.py   # SQLite repository and FTS logic
  tools.py        # explicit agent/tool bridge schemas
scripts/
  smoke.py
  install_launchagent.py
  gemini_dream_distiller.py
tests/
  test_*.py

Security and privacy

PBrain is local-first. The database, exports, logs, backups, virtualenvs, and local .env files are ignored by git.

Before publishing or sharing a repo, check what will be committed:

git status --short
git diff --cached --name-only
git diff --cached

Do not commit runtime data from data/, session logs, API keys, personal exports, or local scheduler logs.

License

MIT. Use it, fork it, simplify it further.