# big-brAIn

AI coding tools have strong temporary context but weak shared organisational memory. A useful discovery made while Alice works with one tool is usually trapped in that private session; Bob's different tool may repeat the same investigation days later. Meanwhile, neither may know that Chen is already changing the same payment service.

**big-brAIn** is a small, working reference implementation of a vendor-neutral engineering memory. It gives different developers and AI coding tools one MCP interface for durable discoveries, time-aware architectural knowledge, and advisory active-work coordination—without sharing private conversations or provider-specific state.

It stores concise, structured facts rather than transcripts. A good record explains something costly to rediscover, says when the underlying fact was observed and valid, distinguishes confidence from certainty, and links back to evidence. The source code, tests, Git history, pull requests, issues, and ADRs remain authoritative.

## Where it fits

| Mechanism | Best used for |
| --- | --- |
| `AGENTS.md` / `CLAUDE.md` | Relatively static repository guidance and working conventions |
| Git / pull requests / ADRs | Durable, source-controlled implementation and decision history |
| big-brAIn memory | Dynamic discoveries, gotchas, investigations, decisions, and time-aware knowledge |
| big-brAIn active work | Transient awareness of what developers and their tools are currently changing |

Sharing complete AI conversations would expose irrelevant prompts, private context, and model-specific internal state while leaving later tools to extract the useful fact themselves. big-brAIn shares only the reusable engineering result and its provenance.

## Architecture

```mermaid
flowchart LR
  A[Developer Alice] --> C1[AI coding tool A]
  B[Developer Bob] --> C2[AI coding tool B]
  C[Developer Chen] --> C3[AI coding tool C]
  C1 -->|MCP over stdio| M[big-brAIn MCP server]
  C2 -->|MCP over stdio| M
  C3 -->|MCP over stdio| M
  M --> S[(shared SQLite database)]
  C1 -. private session .-> C1
  C2 -. private session .-> C2
  C3 -. private session .-> C3
```

The TypeScript MCP adapter, scripted demo, and tests all use the same `MemoryService`, `WorkService`, and SQLite repository. SQLite FTS5 provides lightweight full-text retrieval; structured SQL predicates provide exact provenance, classification, and temporal filters. The repository boundary keeps a later search/storage implementation possible without introducing a vector database now.

The server uses the stable v2 [`@modelcontextprotocol/server`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/packages/server) package and its dual-era `serveStdio()` entry point. Each client can launch its own server process against the same database. SQLite WAL mode coordinates those connections.

## Quick start

Requirements: Node.js 20 or newer and npm.

```bash
git clone https://github.com/jasonpaige/big-brAIn.git
cd big-brAIn
npm install
npm test
npm run seed
npm run demo
```

Normal development commands:

```bash
npm run start      # run the stdio MCP server; creates .data/big-brain.sqlite
npm run seed       # idempotently seed that persistent database with realistic records
npm run demo       # run an in-memory end-to-end scenario
npm test           # run the complete test suite
npm run typecheck  # strict TypeScript validation
npm run lint       # ESLint
npm run build      # emit JavaScript and declarations under dist/
```

Set `BIG_BRAIN_DB` to make several repositories/clients use one explicit database:

```bash
BIG_BRAIN_DB=/absolute/path/to/shared/engineering-memory.sqlite npm run start
```

The parent directory and schema are created automatically. Runtime databases, WAL files, build output, and dependencies are ignored by Git.

## Persistent database example

No Docker service is required. `npm run seed` creates a real SQLite database at `.data/big-brain.sqlite`, then exercises current knowledge, historical validity, and active-work overlap against it. The command is idempotent, so it can be run repeatedly without duplicating its fixture records.

```bash
npm run seed
npm start
```

The server and seed command both honour `BIG_BRAIN_DB`, so the database can live elsewhere:

```bash
BIG_BRAIN_DB=/absolute/path/to/team-memory.sqlite npm run seed
BIG_BRAIN_DB=/absolute/path/to/team-memory.sqlite npm start
```

SQLite is embedded but is still a persistent transactional database. It provides the requested runnable database example with no daemon, container, credentials, or port management. WAL mode supports several local MCP processes using the same file.

## Demo

`npm run demo` exercises the real services and an in-memory SQLite database; its results are not hardcoded. It shows:

1. Alice's tool searches before investigating duplicate payments and finds no relevant memory.
2. Alice announces active work.
3. She records a confirmed, high-confidence gotcha: an HTTP 409 from `PaymentService` means the idempotent payment already completed and must not be retried.
4. She completes the work record.
5. Bob's different tool retrieves that finding without receiving Alice's conversation.
6. Chen starts work touching `src/payments/PaymentService.ts`; Bob detects the overlap.
7. Historical queries show synchronous processing on 2026-02-01 and queue-based asynchronous processing on 2026-08-01.

## MCP tools

The interface deliberately stays small:

| Tool | Purpose |
| --- | --- |
| `memory_search` | Full-text and structured search, including `created*`, `observed*`, `updated*`, and `validAt` filters |
| `memory_record` | Store a discovery, investigation, decision, gotcha, domain rule, or architectural fact with provenance |
| `memory_update` | Correct metadata or enrich a record without representing a change in reality |
| `memory_supersede` | Atomically create a replacement and close/link the previous record's validity |
| `work_start` | Announce advisory active work with likely files and components |
| `work_search` | Find work by text, repository, person/tool, component, status, or exact file overlap |
| `work_update` | Update scope or mark work abandoned/completed |
| `work_complete` | Complete an active-work record with a timestamp |

Example calls an MCP client can make:

```json
{
  "name": "memory_search",
  "arguments": {
    "repository": "example-commerce-platform",
    "query": "payment retry idempotency",
    "confidence": "high"
  }
}
```

```json
{
  "name": "work_search",
  "arguments": {
    "repository": "example-commerce-platform",
    "files": ["src/payments/PaymentService.ts"]
  }
}
```

```json
{
  "name": "memory_record",
  "arguments": {
    "type": "gotcha",
    "title": "HTTP 409 means an idempotent payment already succeeded",
    "summary": "Treat PaymentService HTTP 409 as success; retrying can duplicate downstream processing.",
    "repository": "example-commerce-platform",
    "components": ["payments", "retry-policy"],
    "tags": ["idempotency", "http-409"],
    "status": "confirmed",
    "confidence": "high",
    "observedAt": "2026-06-02T12:15:00Z",
    "provenance": {
      "human": "Alice",
      "agent": "Codex",
      "repository": "example-commerce-platform",
      "branch": "investigate/duplicate-payments",
      "commit": "4f8c2ab",
      "issue": "PAY-1842",
      "files": ["src/payments/PaymentService.ts", "src/payments/RetryPolicy.ts"],
      "evidence": ["An integration test reproduced 409 after a completed idempotency key."]
    }
  }
}
```

Tool handlers return JSON as MCP text content. Invalid tool inputs are rejected by the SDK's Zod validation; domain failures are returned with `isError: true` so the calling model can react.

## Time-aware memory

Time is part of the model, not a display detail:

- `createdAt`: when this record was written.
- `updatedAt`: when this record's metadata was last changed.
- `observedAt`: when the underlying evidence was actually observed or verified.
- `validFrom`: earliest instant at which the fact is believed to have been true.
- `validUntil`: first instant at which it should no longer be considered true.
- `supersededAt`: when a replacement explicitly took over.

All supplied ISO-8601 dates/date-times are normalized to UTC and stored as canonical `...Z` strings. Date-only inputs such as `2026-02-01` mean midnight UTC. Validity uses a half-open interval: `[validFrom, validUntil)`. A missing endpoint is unbounded.

Suppose memory A says payment processing is synchronous from 2025-01-01. On 2026-04-17, memory B says payment events now go through a queue. `memory_supersede` preserves A, marks it `superseded`, links `A.supersededBy` to B, and ends A's validity at the effective instant.

```mermaid
timeline
  title Payment architecture validity
  2025-01-01 : A — synchronous processing becomes valid
  2026-02-01 : validAt returns A
  2026-04-17 : B supersedes A : asynchronous queue processing becomes valid
  2026-08-01 : validAt returns B
```

A normal current search excludes superseded records unless `includeSuperseded: true`. A `validAt` search instead evaluates the validity interval and can return a now-superseded record that was true at the requested time. At the boundary instant, the old record is excluded and the replacement is included.

This is validity time, not omniscient historical reconstruction: a fact can have `validFrom` earlier than `createdAt` because evidence discovered today may establish what was true months ago.

## Connect from Codex

Build once, then register the emitted stdio server. The current Codex CLI accepts the launch command after `--`:

```bash
npm install
npm run build
codex mcp add big-brain \
  --env BIG_BRAIN_DB=/absolute/path/to/shared/engineering-memory.sqlite \
  -- node /absolute/path/to/big-brAIn/dist/index.js
codex mcp list
```

For configuration as code, adapt [`examples/codex/config.toml`](examples/codex/config.toml) into `~/.codex/config.toml` or a project-scoped `.codex/config.toml`. Current Codex configuration uses a `[mcp_servers.<name>]` table with `command`, `args`, optional `cwd`, and an `env` subtable. See the official [Codex MCP documentation](https://developers.openai.com/codex/mcp).

Merge the guidance in [`examples/codex/AGENTS.example.md`](examples/codex/AGENTS.example.md) into the consuming repository's instructions.

## Connect from Claude Code

After `npm run build`, add the same stdio process at project scope:

```bash
claude mcp add big-brain --scope project \
  --env BIG_BRAIN_DB=/absolute/path/to/shared/engineering-memory.sqlite \
  -- node /absolute/path/to/big-brAIn/dist/index.js
claude mcp get big-brain
```

Alternatively, adapt [`examples/claude/.mcp.json`](examples/claude/.mcp.json) in the consuming project. Claude Code asks users to approve project-scoped servers. Use `/mcp` inside Claude Code to inspect the connection. See Anthropic's official [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).

Merge [`examples/claude/CLAUDE.example.md`](examples/claude/CLAUDE.example.md) into that project's guidance.

The absolute `BIG_BRAIN_DB` path is the coordination point. If every client uses its default working-directory-relative database, they will not share knowledge.

## Recording threshold

Record something when another competent engineer would benefit and rediscovery would take meaningful effort.

Good:

> Do not retry PaymentService HTTP 409 responses. In this API, 409 means the idempotency key already completed successfully.

Too trivial:

> `PaymentService` is in `src/payments/PaymentService.ts`.

Statuses (`hypothesis`, `observed`, `confirmed`, `decision`, `superseded`) and confidence (`low`, `medium`, `high`) express different ideas. A strongly held theory is still a hypothesis until evidence changes its status. The service never promotes one automatically.

Provenance is mandatory and must contain at least one non-empty source field. It can identify the developer, AI tool, repository, branch, commit, pull request, issue, files, URLs, and free-text evidence. Do not put secrets or private reasoning in evidence.

## Storage and search details

- SQLite tables store canonical fields; arrays and provenance use validated JSON columns.
- FTS5 indexes titles, summaries, details, components, tags, provenance, work descriptions, and paths.
- Free-text terms use OR matching and BM25 ranking. Exact filters can narrow repository, type, status, confidence, person/tool, component, tag, and file.
- File-overlap search is exact path matching against any supplied path; it does not claim ownership or block work.
- Supersession inserts the replacement and updates the old record in one SQLite transaction.
- Result limits default to 20 and are capped at 100.

## Project structure

```text
big-brAIn/
├── .gitignore
├── AGENTS.md
├── LICENSE
├── README.md
├── package.json
├── package-lock.json
├── tsconfig.json
├── tsconfig.build.json
├── vitest.config.ts
├── examples/
│   ├── claude/
│   │   ├── .mcp.json
│   │   └── CLAUDE.example.md
│   └── codex/
│       ├── AGENTS.example.md
│       └── config.toml
├── src/
│   ├── demo.ts
│   ├── domain.ts
│   ├── index.ts
│   ├── mcp.ts
│   ├── seed.ts
│   ├── services.ts
│   ├── storage.ts
│   └── time.ts
└── tests/
    ├── mcp.test.ts
    └── memory.test.ts
```

## What this is not

- **Not shared chain-of-thought or chat history.** It stores concise outcomes, not model reasoning or transcripts.
- **Not a replacement for colleagues talking.** Active work is advisory awareness, not team coordination by itself.
- **Not a replacement for Git, tests, documentation, issues, pull requests, or ADRs.** Records should point to those sources.
- **Not automatically authoritative.** Memory may be stale, incomplete, low-confidence, or wrong; conflicts should trigger investigation.
- **Not merge-conflict prevention.** File overlap is a warning, not a lock.
- **Not production multi-tenant infrastructure.** The reference server has no authentication, authorisation, encryption, quotas, retention policy, or tenant isolation.
- **Not semantic search.** FTS5 is intentional for a transparent local example; the repository boundary permits a later backend.

## Limitations and next steps

The stdio server is intended for trusted local/team environments with filesystem access to one SQLite file. SQLite is excellent for this demonstration and modest teams but a networked deployment would need authentication, tenant boundaries, migrations/versioning, backups, access control, audit policy, and likely an HTTP transport. Text search understands terms, not meaning. Provenance is stored, not independently verified. Active-work records can become stale if a client crashes before completion.

These limitations keep the example focused on the core pattern: portable structured memory, explicit time and provenance, honest uncertainty, retained history, and lightweight work awareness.

## Development

Tests use deterministic clocks and in-memory databases. They cover recording, full-text and structured search, creation/observation/update filters, UTC normalization, validity boundaries, supersession and historical retrieval, provenance, active-work updates/completion, and file/component overlap.

Before submitting a change:

```bash
npm test
npm run typecheck
npm run lint
npm run build
npm run demo
```

Licensed under the [MIT License](LICENSE).