memlay

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. Linux/macOS — cargo install memlay --locked (crates.io).

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

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:

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):

memlay mcp --stdio

The server exposes exactly three tools: context, expand, record.

Recording knowledge

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):

memlay check --ci --base origin/main --require-change-record

Browsing memory as documentation

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.

Layout

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