Brain

Local-first memory for coding agents.

Brain watches allowlisted Codex and Claude Code session files, stores normalized events in SQLite, and writes Markdown notes that can later be searched, distilled, linked, and used as agent context.

It is an early prototype for a bigger idea: a durable, inspectable memory layer that sits beside coding agents without taking ownership of their internal state.

Why

Coding agents leave useful context behind:

• decisions made during implementation
• commands that worked or failed
• project conventions discovered during debugging
• explanations that should not be rediscovered next week
• links between sessions, projects, concepts, and follow-up tasks

Most of that context is trapped in session logs. Brain turns those logs into a local memory substrate: raw events in SQLite, human-readable Markdown in a vault-like folder, and eventually compact context packs for future agents.

Current Status

Brain is usable as a local prototype, not yet a polished background memory service.

It currently supports:

• narrow allowlisted discovery of Codex and Claude Code JSONL files
• incremental JSONL tailing with stored offsets
• duplicate-resistant SQLite event storage
• Markdown output under memory/
• basic scan, watch, query, and status commands

The next major work is source-specific parsing and distillation so Markdown becomes summaries, decisions, project facts, and concepts instead of raw event dumps. See ROADMAP.md.

Install

Install from source:

go install github.com/forjd/brain/cmd/brain@latest

Or clone and run locally:

git clone https://github.com/forjd/brain.git
cd brain
go run ./cmd/brain init

Quick Start

brain init
brain scan
brain status
brain query "agent skill"
brain watch

When running from a local checkout without installing:

go run ./cmd/brain init
go run ./cmd/brain scan
go run ./cmd/brain query "agent skill"

Commands

brain init [-config path] [-force]
brain scan [-config path] [-dry-run]
brain watch [-config path] [-interval 10s]
brain query [-config path] [-limit 10] <terms>
brain status [-config path]

init

Creates brain.config.json, initializes the SQLite database, and creates the Markdown memory directory.

scan

Discovers configured JSONL files, reads only new content since the last stored offset, stores normalized events, and writes text-bearing entries to Markdown.

Use -dry-run to inspect parse counts without writing events, offsets, or Markdown.

watch

Runs the scanner continuously using filesystem notifications with a polling fallback.

query

Performs a simple local text search over stored event text.

status

Prints the active config, database path, memory path, discovered source count, and ingested event totals.

Default Sources

Brain intentionally does not scan entire agent directories. The generated config reads only these JSONL patterns:

~/.codex/history.jsonl
~/.codex/session_index.jsonl
~/.codex/archived_sessions/*.jsonl
~/.claude/history.jsonl
~/.claude/projects/*/*.jsonl

Runtime output stays in the project directory by default:

var/brain.db
memory/daily/*.md
memory/sources/*.md

Those runtime paths are ignored by git.

Configuration

brain.config.json controls storage paths, source patterns, and scanner behavior:

{
  "db_path": "./var/brain.db",
  "memory_dir": "./memory",
  "max_text_bytes": 8000,
  "poll_interval_seconds": 10,
  "sources": [
    {
      "name": "codex",
      "kind": "jsonl",
      "enabled": true,
      "patterns": [
        "~/.codex/history.jsonl",
        "~/.codex/session_index.jsonl",
        "~/.codex/archived_sessions/*.jsonl"
      ]
    }
  ]
}

Use explicit file patterns where possible. Avoid broad patterns that sweep up auth files, settings, caches, shell snapshots, or unrelated application state.

Privacy Model

Brain is local-first and reads source files directly from your machine. That is useful, but it also means session content can include sensitive material.

Current safeguards:

• source directories are read-only
• discovery is allowlist-based
• runtime output is written outside .codex and .claude
• generated runtime data is ignored by git
• known config/auth/cache directories are not part of the defaults

Important limitations:

• the current prototype does not yet redact secrets
• raw session text may be stored in var/brain.db
• text-bearing events may be written into memory/daily
• you should not publish memory/, var/, or brain.config.json without reviewing them

Redaction, retention controls, and distilled notes are planned in the roadmap.

Architecture

Codex / Claude Code JSONL files
        |
        v
source discovery
        |
        v
incremental JSONL tailer
        |
        v
normalized event model
        |
        +--> SQLite event store
        |
        +--> Markdown memory directory

The current parser is intentionally generic. Source-specific Codex and Claude Code adapters are planned so Brain can distinguish user turns, assistant turns, tool calls, commands, projects, sessions, decisions, and tasks.

Development

go test ./...
go build ./cmd/brain

The project uses:

• Go
• SQLite via modernc.org/sqlite
• filesystem watching via fsnotify

Roadmap

Near-term priorities:

• add tests and fixtures around ingestion
• add source listing and offset reset commands
• implement source-specific Codex and Claude Code parsers
• replace raw Markdown dumps with distilled session notes
• add privacy redaction and retention controls
• add brain context for compact agent-ready context packs

See ROADMAP.md for the full plan.

Contributing

Issues and pull requests are welcome. Good early contributions include parser fixtures, safer redaction rules, tests for offset handling, and improvements to the Markdown memory model.

For now, keep changes small and local-first. Brain should remain useful without hosted services or mandatory network calls.

License

Brain is released under the MIT License.