# memlay
[](https://github.com/runetime-games/memlay/actions/workflows/ci.yml)
[](https://github.com/runetime-games/memlay/releases)
Repo-native, conflict-resistant shared memory and codebase navigation layer for AI coding agents (Codex, Claude Code, and any MCP client).
**Install:** Windows — download `memlay.exe` from the [latest release](https://github.com/runetime-games/memlay/releases). Linux/macOS — `cargo install memlay --locked` ([crates.io](https://crates.io/crates/memlay)).
Durable team memory lives inside your Git repository as small immutable records. Fast indexes live in Git metadata and are never committed. Every context response identifies the exact team-memory revision it used, so every developer's agent works from the same canonical knowledge.
## Why
Teams using AI agents repeatedly pay to rediscover the same decisions, constraints, and history — and different developers' agents operate from inconsistent knowledge. memlay makes project memory:
- **Authoritative** — the baseline branch's committed records are shared team truth; branch and uncommitted records are explicit overlays, always labeled.
- **Immutable and merge-proof** — one record per uniquely named file; updates supersede, never edit. Two branches can add memory in parallel with zero Git conflicts; contradictions surface as *semantic conflicts* that are never silently resolved.
- **Navigable** — `context` returns a token-budgeted codebase table of contents: relevant modules, symbols, tests, decisions with rationale, and chronological change history with who/when/which agent.
- **Local and fast** — SQLite + tree-sitter indexes under `.git/`, no network on the critical path, no LLM or embedding API required.
## Quick start
```bash
cargo install --path .
cd your-project
memlay init # .memlay/, config, Codex + Claude integration
memlay backfill --since 2y # optional: draft records from Git history
memlay sync # fetch + index the team baseline
memlay context "add retry handling to payment webhooks" --budget 1000
```
Orientation in an unfamiliar repo — the whole codebase as a map, at minimal token cost:
```bash
memlay map # module tree: files, symbols, purposes, edges (~200-800 tokens)
memlay map --depth 2 --scope apps
memlay expand module:apps/api # drill into one module: files, symbols, memory, imports
```
Module purposes come from human-approved `architecture` records when they exist (`::`), else are derived from READMEs and package manifests (`:~`, always marked). Over MCP, agents reach the same map via `expand` with ref `module:.`.
Agents connect through MCP (installed by `memlay init`):
```bash
memlay mcp --stdio
```
The server exposes exactly three tools: `context`, `expand`, `record`.
## Recording knowledge
```bash
memlay record --kind decision --key payments.webhook.retry-policy \
--summary "Payment events retry five times with exponential backoff." \
--rationale "Transient provider failures must not discard events." \
--scope apps/worker/src/payments --tag payments
memlay record --draft-from-diff # pre-filled change record from your diff
memlay history payments.webhook.retry-policy
memlay conflicts # semantic conflicts (multiple heads)
memlay resolve <key> --supersede <id> --supersede <id> --summary "..."
memlay diff --base origin/main --format markdown # PR review summary
```
CI gate (requires a change record covering nontrivial source changes):
```bash
memlay check --ci --base origin/main --require-change-record
```
## Browsing memory as documentation
```bash
memlay docs # single markdown view to stdout
memlay docs --out generated-docs # write memory.md to a directory
memlay docs --out generated-docs --split # one file per area + index.md
```
`--split` groups records by their top-level key namespace (`payments.*` → `payments.md`) with decisions, rationale, aliases, conflict markers, and each area's related change history, plus an `index.md` overview. Generated views are derived, never canonical, and should not be committed.
memlay's own reference docs are self-maintaining: `memlay docs --reference` renders the CLI reference, MCP tool contracts, config defaults, error codes, and module inventory from the binary into marked blocks inside `docs/`, and `--check` fails CI when they drift.
## Layout
| `.memlay/records/**/*.mly` | Immutable memory records (MRF v1) | yes |
| `.memlay/config.toml` | Project configuration | yes |
| `<git-dir>/memlay/` | SQLite index, drafts, spools, state | never |
| `<git-common-dir>/memlay/` | Shared parse cache, audit staging | never |
| `refs/memlay/audit/<writer>` | Finalized audit bundles | dedicated refs |
## Security posture
- All data stays local; `memlay sync` is an ordinary authenticated `git fetch`.
- Repository code is never executed during indexing; paths are boundary-checked.
- Audit events are secret-redacted before they touch disk.
- Memory text is rendered inside `MEMORY_DATA_BEGIN`/`END` delimiters and marked as data, not instructions. This is defense-in-depth, **not** a guarantee — models may still follow malicious text inside data. The primary defenses are provenance trust labels and human review of what merges to the baseline. See `docs/security.md`.
## Documentation
`docs/` covers architecture, the MRF record format, team-memory revisions and sync, the codebase map, Git behavior and conflicts, MCP contracts, Codex/Claude setup, security, performance, and backfill.
## Status and limitations
P0 feature set per the PRD. Genuine P1 omissions: HTTP MCP transport, semantic retrieval providers, filesystem watch mode (`serve`), operational epoch archival (the format contract is reserved), `gh`/LLM backfill providers, and the local stats dashboard. Windows, macOS, and Linux are supported.
## License
Apache-2.0