Long-term memory for AI coding agents and the developers who work alongside them.

Postbrain gives agents (Claude Code, OpenAI Codex, GitHub Copilot, and others) a persistent, queryable store that survives session termination and context resets.

It exposes three layers backed by PostgreSQL:

Quick Start

Prerequisites:

• PostgreSQL 18 with required extensions (pgvector, apache_age, pg_cron, pg_partman)
• Go 1.26+
• Embedding provider (for example Ollama or OpenAI-compatible endpoint)

Then:

# 1) Start local Postgres (dev image with required extensions)
docker compose up -d postgres

# 2) Create config and adjust values as needed
cp config.example.yaml config.yaml

# 3) Build binaries
make build

# 4) Bootstrap admin principal + initial token
./postbrain onboard --config ./config.yaml --slug admin --display-name "Postbrain Admin" --token-name "bootstrap-admin"

# 5) Run server
./postbrain --config ./config.yaml

Default server address is http://localhost:7433.

Documentation

Use README.md for orientation; use docs/ for complete guidance.

• Documentation Home
• Getting Started
• Server Installation
• Configuration Reference
• Using with Coding Agents
• Common Workflows
• Web UI Guide
• Security and Access Model
• Access Control Reference
• Operations
• Troubleshooting Playbook

API and MCP

• REST API auth and examples: docs/api-auth-examples.md
• MCP usage patterns: docs/common-workflows.md
• OAuth login/server setup: docs/oauth-logins.md

Repository Layout

postbrain/
├── cmd/                      # server + CLI entrypoints
├── internal/                 # application packages (api, db, authz, memory, knowledge, skills, ui)
├── docs/                     # canonical user/operator documentation
├── designs/                  # architecture and task tracking docs
├── config.example.yaml       # reference configuration
└── docker-compose.yml        # local dev stack

For Agents

Before making changes, read these in order:

1. AGENTS.md (mandatory coding and workflow rules)
2. docs/index.md (starting point for selecting additional designs/ documents to read in full)
3. designs/DESIGN.md (high-level architecture overview and invariants)
4. subsystem-specific design/task files identified from docs/index.md (for example permissions, OAuth, code graph)
5. designs/TASKS.md (task tracking, must be updated before commit)