nexus — long-term team brain

nexus (Greek: νοῦς) — mind, intellect, intuition. The faculty that sees things as they are.

nexus is a long-lived, team-shareable project memory. It is:

• Just markdown files in a folder. No DB to run, no server to host.
• Date-stamped and owner-attributed. Every entry carries [YYYY-MM-DD owner]. Grep works forever.
• Append-only. Nothing is ever auto-deleted. Old engineering rules are load-bearing, not stale.
• Tool-agnostic. Auto-generates CLAUDE.md, AGENTS.md, .cursor/rules/brain.mdc, .github/copilot-instructions.md — every AI tool you use reads the brain through its native discovery, no extra config.
• Forward-compatible. Schema versioned. A nexus from 2046 will still read a brain written in 2026, and vice versa.

Why

Teams accumulate knowledge faster than they document it. The brain is where that knowledge goes to live for decades — surviving turnover, tool churn, and reorgs.

When someone leaves: their brain/rules/<them>.md stays. Their decisions, their patterns, their gotchas — all dated, all attributed. The next person reads brain/ on day one and inherits the team's mental model.

Quickstart

pip install nexus-md                      # `nexus` on PyPI is an
                                          # unrelated 2015 package
cd ~/my-repo
nexus init                                # creates brain/ + AI tool mirrors
nexus learn-from "always use httpx, never requests — async-first codebase"

That's it. Open Claude Code / Cursor / Codex / Copilot in this repo — all four now read this rule automatically via their native discovery files.

Folder structure

brain/
├── README.md                       intro for humans
├── rules/<owner>.md                hard constraints, never break these
├── logic/<owner>.md                business/domain logic
├── code/<owner>.md                 patterns, conventions, architecture
├── stack/<owner>.md                tech stack, versions
├── data/<owner>.md                 schemas, field definitions
├── goals/<owner>.md                project objectives, scope
├── decisions/<owner>.md            ADR-style: chosen approach + why
├── glossary/<owner>.md             domain term definitions
└── personas/<owner>.md             tone, behavior, communication style

Per-owner sub-files mean two teammates writing simultaneously never conflict at the file level. You can also use single-file mode (brain/rules.md); the reader handles both.

CLI

nexus init                            # create brain/ in cwd
nexus learn-from "<rule>"             # append to rules/<you>.md, dated
nexus show [bucket]                   # grep-first search
  --since 2026-01-01
  --until 2026-05-31
  --by ayushi
  -q pattern
  --json
nexus usage                           # counts per bucket + owner
nexus own                             # print your owner slug
nexus sync                            # regenerate AI-tool mirrors
nexus unmirror                        # remove mirrors (opt-out)
nexus spec                            # print SPEC.md

Auto-generated mirrors

After every nexus write, four files at repo root are regenerated:

Each carries <!-- GENERATED — DO NOT EDIT -->. Edit brain/; mirrors follow. To opt out: nexus unmirror.

Per-team use cases

Engineering — Drop your rules in brain/rules/<you>.md. Cursor / Claude Code / Codex see them all automatically.

Data — brain/glossary/<you>.md is the canonical home for metric definitions. "What does 'active user' mean?" gets answered once, forever.

Analytics — brain/decisions/<you>.md for revenue recognition, attribution choices. Date stamps make the rationale auditable.

Business / PMs — Edit any .md via GitHub web UI; commits become PRs through your normal review flow. No CLI required.

Long-term contracts

• No auto-delete. Ever. The brain only grows. Old rules are load-bearing.
• Append-only history. When a rule changes, write a new chunk that supersedes the old one; the old one stays on disk forever.
• Forward-compat. Unknown fields in chunk JSONL are dropped on read, not crashed. Your 2026 install reads 2046 brains and vice versa.
• No required services. A brain is markdown files. Anything that reads files reads the brain.

Full format contract: see SPEC.md.

License

MIT.

Related

Built originally as the substrate layer of polymath, a multi-model AI orchestrator. Extracted into its own repo so any AI tool, not just Polymath, can use the format.