big-brAIn

Imported from jasonpaige/big-brAIn (AGENTS.md). Install upstream with npx skills add jasonpaige/big-brAIn. Copyright stays with the author.

AGENTS.md

Project

This repository is big-brAIn: a working reference implementation of a shared engineering memory for AI coding agents.

The goal is to demonstrate how multiple developers using different AI coding agents, such as Codex and Claude Code, can share durable engineering knowledge and awareness of active work without sharing conversation history or model-specific internal state.

The repository should remain small enough to understand easily, but complete enough to run locally and demonstrate the pattern end-to-end.

Core idea

AI coding agents often rediscover the same information independently.

Useful knowledge is commonly trapped in:

• an individual developer's head;
• an AI conversation;
• a temporary investigation;
• a branch that another developer has not seen;
• Slack/Teams messages;
• a pull request discussion;
• or undocumented assumptions about a codebase.

big-brAIn provides a shared, vendor-neutral memory layer.

Agents can:

1. search previously discovered engineering knowledge;
2. record new discoveries;
3. record architectural decisions and their reasoning;
4. see work currently being performed by other agents/developers;
5. record completion of active work;
6. reason about knowledge as it existed at a particular point in time.

The initial interoperability mechanism is MCP.

The shared memory is external to any particular AI provider.

Important design principle

This system is NOT a shared AI conversation.

Do not attempt to persist chain-of-thought, entire prompts, complete chat histories, or arbitrary agent transcripts.

Persist concise, structured, reusable engineering knowledge.

Examples:

• non-obvious behaviour;
• architectural constraints;
• investigation findings;
• gotchas;
• important domain rules;
• reasons behind decisions;
• known failure modes;
• links between components;
• active engineering work;
• historical facts that may later cease to be true.

Do not record facts that are trivial to rediscover directly from the code.

Time is first-class

Every memory must contain temporal information.

At minimum store:

• createdAt
• updatedAt
• observedAt

Where useful, also support:

• validFrom
• validUntil
• supersededAt

These timestamps have different meanings.

createdAt : When the memory record was created.

observedAt : When the underlying fact was observed or verified.

validFrom : The earliest point at which the fact is believed to have been true.

validUntil : The point after which the fact should no longer be considered true.

supersededAt : When another memory or decision explicitly replaced this one.

This distinction is important.

For example, an agent might record something today that was discovered from logs showing that the behaviour existed three months ago.

Agents must be able to search using temporal constraints.

Examples:

• knowledge known after 2026-01-01;
• knowledge observed before 2026-06-01;
• knowledge believed valid on 2026-03-15;
• memories created during the last 30 days;
• ignore memories older than a supplied date;
• reconstruct the known architecture at a historical point in time.

Do not assume that the newest memory is automatically correct.

Provenance is mandatory

A useful engineering memory must explain where it came from.

Memories should support provenance including:

• developer;
• agent;
• repository;
• branch;
• commit SHA;
• pull request;
• issue/ticket;
• file paths;
• URLs;
• free-text evidence.

Where applicable, record the commit at which a finding was verified.

Example:

source:
  human: Jason
  agent: codex
  repository: example-service
  branch: investigate/video-sync
  commit: 728af9c
  files:
    - src/media/VideoImporter.ts
    - src/media/TrimService.ts

Confidence and status

Memories are not necessarily facts.

Support a status such as:

• hypothesis
• observed
• confirmed
• decision
• superseded

Support confidence:

• low
• medium
• high

Agents should distinguish between an unverified theory and something verified by code/tests/production evidence.

A hypothesis must never silently become a confirmed fact.

Memory types

The initial system should support at least:

discovery

A reusable fact learned while working with the system.

investigation

The result of investigating a problem or behaviour.

decision

An architectural or implementation decision, including reasoning.

gotcha

Something surprising that another engineer is likely to trip over.

domain-rule

A business/domain behaviour that is not obvious from individual pieces of code.

architecture

Knowledge about component relationships or system structure.

Other types can be added later without changing the fundamental model.

Superseding memories

Engineering knowledge changes.

Never silently overwrite an old memory merely because reality changed.

Where useful, retain the previous record and create a new record that supersedes it.

Example:

Memory A
"Video imports are processed synchronously."
validFrom: 2025-03-01
validUntil: 2026-05-14
supersededAt: 2026-05-14

Memory B
"Video imports are processed asynchronously using the import queue."
validFrom: 2026-05-14

This enables historical queries and prevents the memory store from pretending that current knowledge was always true.

Active work

The system must also provide lightweight coordination between agents.

An agent should be able to announce active work containing fields such as:

• developer;
• agent;
• repository;
• branch;
• task;
• description;
• likely files;
• likely components;
• startedAt;
• updatedAt;
• status.

Statuses should include:

• active
• completed
• abandoned

Active work is advisory, not locking.

The purpose is to let another agent detect likely overlap.

For example:

Another agent is currently modifying MigrationService.ts on branch
feature/ABC-123.

The second agent may still proceed.

The system should provide information rather than enforce ownership.

MCP interface

Expose the shared memory through an MCP server.

Keep the MCP API small and comprehensible.

At minimum provide tools equivalent to:

memory_search
memory_record
memory_update
memory_supersede

work_start
work_search
work_update
work_complete

Exact names may evolve, but avoid an unnecessarily large API.

memory_search

This is the most important operation.

Support useful combinations of:

• free-text query;
• repository;
• memory type;
• status;
• confidence;
• developer;
• agent;
• file;
• component/tag;
• created after/before;
• observed after/before;
• valid at date/time;
• updated after/before;
• include/exclude superseded memories;
• result limit.

A query must not require every field.

Examples:

Find knowledge about video import timestamps.

Find confirmed knowledge about authentication discovered since
2026-01-01.

What did we believe about the media import pipeline on
2026-03-01?

Ignore anything not observed within the last six months.

Storage

For the reference implementation prefer:

• TypeScript;
• Node.js;
• SQLite.

Do not introduce Postgres, Redis, Elasticsearch, or a vector database merely because a production implementation might use them.

The example should be clonable and runnable with minimal setup.

Design repository/storage abstractions so another backend could be added later.

SQLite full-text search is acceptable.

A later implementation may add semantic/vector search, but it is not required to demonstrate the pattern.

Demo

The repository must contain an end-to-end demonstration.

Include a small example codebase or fixtures representing a fictional engineering system.

The demonstration should show at least two agents/developers.

Example flow:

1. Developer A starts an investigation.
2. Agent A checks existing memory.
3. Agent A records active work.
4. Agent A discovers a non-obvious behaviour.
5. Agent A records the discovery with provenance and date information.
6. Agent A completes the active work.
7. Developer B starts a separate task.
8. Agent B searches shared memory.
9. Agent B retrieves Developer A's finding without receiving Developer A's original conversation.
10. Agent B changes behaviour or avoids duplicate investigation because of that knowledge.

Also demonstrate temporal behaviour:

1. record an old architectural fact;
2. record a newer fact superseding it;
3. query current knowledge;
4. query knowledge valid at a historical date;
5. show different answers.

Also demonstrate overlapping work detection.

Sample data

Provide useful seed/demo data.

Avoid lorem ipsum.

Use realistic software engineering examples such as:

• authentication;
• media processing;
• database migrations;
• event consumers;
• caching;
• API behaviour.

The examples should make the benefit of shared engineering memory immediately obvious.

Agent instructions

Include example integration instructions for both:

• Codex;
• Claude Code.

Do not assume either agent has proprietary access to the other.

Both should communicate only through the shared MCP interface.

Include example agent guidance along these lines:

Before a substantial investigation:
- search engineering memory;
- search active work.

Before modifying an unfamiliar area:
- search for relevant discoveries, decisions and gotchas;
- check for overlapping active work.

During an investigation:
- record durable, non-obvious findings;
- distinguish hypotheses from confirmed findings;
- include provenance.

When engineering knowledge changes:
- supersede old knowledge rather than silently destroying history.

On completion:
- mark active work complete;
- record any durable knowledge that would save another engineer
  meaningful investigation time.

Recording threshold

Do NOT record everything.

A memory should generally be recorded when another competent engineer would benefit from knowing it later and it would otherwise require meaningful effort to rediscover.

Good:

The user deletion event is deliberately handled asynchronously because
the identity provider can take up to 30 seconds to make the user
unavailable through its API.

Bad:

UserService is in src/services/UserService.ts.

Good:

Do not retry HTTP 409 responses from PaymentService. In this API a 409
means the idempotency key has already completed successfully.

Bad:

PaymentService uses HTTP.

Source of truth

big-brAIn complements rather than replaces:

• source code;
• Git history;
• tests;
• documentation;
• ADRs;
• issues;
• pull requests.

Memory entries should link to these sources where appropriate.

When a memory conflicts with executable code or newer authoritative documentation, agents should investigate rather than blindly trusting the memory.

Repository quality

The repository is intended to be public at:

github.com/jasonpaige/big-brAIn

Treat it as a reference/demo project.

It must have:

• a clear README;
• simple setup;
• sensible project structure;
• TypeScript strict mode;
• formatting/linting;
• automated tests;
• useful example data;
• MCP configuration examples;
• no committed secrets;
• no unnecessary infrastructure.

Prefer readability over cleverness.

Testing

Tests should cover at least:

• recording memories;
• querying memories;
• text search;
• temporal filtering;
• validAt behaviour;
• superseding memories;
• provenance;
• status/confidence filtering;
• active work;
• completion of work;
• overlap searching.

Temporal behaviour is core functionality, not an optional edge case.

Documentation

The README should explain the problem before explaining the implementation.

A reader should understand within the first few paragraphs:

AI coding agents have excellent temporary context but poor shared organisational memory. big-brAIn demonstrates a vendor-neutral engineering memory that allows different agents working for different developers to share durable discoveries and coordinate active work.

Include architecture diagrams using Mermaid where useful.

Document limitations honestly.

In particular explain that this example does not attempt to:

• share model chain-of-thought;
• replace human communication;
• make stored knowledge automatically trustworthy;
• prevent merge conflicts;
• replace Git or documentation;
• provide production-grade authentication/multi-tenancy.

Development approach

When implementing changes:

1. understand the current repository before editing;
2. make the smallest coherent change;
3. add or update tests;
4. run relevant tests;
5. run lint/typecheck;
6. update documentation when behaviour changes.

Do not leave placeholder implementations where a working example is reasonably achievable.

Avoid unnecessary abstractions.

The primary objective is to make the shared-agent-memory pattern obvious, credible and easy to experiment with.