Metadata-Version: 2.4
Name: nexus-md
Version: 0.3.0
Summary: Long-term team brain — markdown + JSONL, date-stamped, owner-attributed, append-only. Auto-generates CLAUDE.md / AGENTS.md / .cursor / Copilot mirrors so every AI tool reads it for free.
Author: Ayushi Gupta
License: MIT
Project-URL: Homepage, https://github.com/ayushigupta-29/nexus
Project-URL: Repository, https://github.com/ayushigupta-29/nexus
Project-URL: Format spec, https://github.com/ayushigupta-29/nexus/blob/main/SPEC.md
Keywords: ai,memory,context,team-brain,claude,cursor,codex,copilot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: embed
Requires-Dist: google-genai>=1.0.0; extra == "embed"
Requires-Dist: openai>=1.50.0; extra == "embed"
Requires-Dist: sqlite-vec>=0.1.6; extra == "embed"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# 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

```bash
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

```bash
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:

| Mirror | Tool | Auto-discovered |
|---|---|---|
| `CLAUDE.md` | Claude Code | ✓ |
| `AGENTS.md` | Codex CLI | ✓ |
| `.cursor/rules/brain.mdc` | Cursor | ✓ |
| `.github/copilot-instructions.md` | GitHub Copilot | ✓ |

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`](./SPEC.md).

## License

MIT.

## Related

Built originally as the substrate layer of
[polymath](https://github.com/ayushigupta-29/polymath), a multi-model
AI orchestrator. Extracted into its own repo so any AI tool, not just
Polymath, can use the format.
