Engrm

Local vector memory for projects and repos — wiki-shaped for humans, MCP-shaped for agents, synced across devices.

See SCOPE.md and HARNESS.md.

Just works

This laptop (all agents share memory)

bun run src/cli.ts setup
# or: npx engrm setup

That initializes local memory (if needed) and registers Cursor, Claude Code, OpenCode, and Codex. Restart agent sessions once. After that, agents share one DB + vault automatically — no per-chat setup.

Agent machines (zero-touch, fleet token)

For machines that run agents with no person to sign in. An admin makes a token once on the hub: Team → Agent fleet tokens → Create token. It is shown once; keep it in your secrets store (1Password, the CI or MDM secret store), not in a repo.

On each machine (Node 22 or later):

ENGRM_FLEET_TOKEN="$TOKEN_FROM_YOUR_SECRET_STORE" npx --yes engrm@latest setup

That installs Engrm, registers Claude Code, Codex, Cursor and OpenCode, signs the machine in to the team hub and pulls the company topics, with no prompts. --yes stops npx asking to install. The token is read from the environment, so it stays out of the process list; --token=… also works. A machine already set up can join with ENGRM_FLEET_TOKEN=… engrm login.

• Keep it syncing. On macOS, setup installs a launchd agent that syncs in the background. On Linux, run engrm mesh daemon under your service manager, for example a systemd user unit with ExecStart=engrm mesh daemon and Restart=always.
• Codex needs one approval. Codex runs Engrm's hooks only after they are trusted: run codex once and approve them in /hooks. Until then Codex gets the MCP tools but records nothing. Claude Code needs nothing.
• Restart agents that were open before setup, so they load Engrm.
• What the hub shows. Each machine appears on its own on the Devices page, under the token's name ("Fleet: Codex runners"), and every memory records the machine and agent that wrote it.
• Revoke. Revoking the token on the Team page signs every machine that joined with it out at once. Make a new token to bring machines back.

Check a machine with engrm status: Team hub shows the hub as reachable, and Agents shows each agent as registered.

Other devices

Option A — LAN mesh (local SQLite per Mac, no cloud)

# Machine 1
engrm mesh init --cluster=optaro
# note the printed mesh_key

# Machine 2
engrm mesh join --key=<mesh_key> --cluster=optaro --peer=<machine1-ip>:7432
engrm mesh sync

Peers discover via UDP multicast and optional static --peer list. Each machine keeps its own SQLite; observations replicate over HTTP (shared+personal, never secret). Optional always-on: engrm mesh install-service.

Option B — Shared folder (no Engrm account)

Point both machines at the same vault directory (iCloud Drive, Syncthing, etc.):

// ~/.engrm/settings.json
{ "vault": { "root": "~/Library/Mobile Documents/com~apple~CloudDocs/EngrmVault" } }

Run engrm setup on each machine. Newer vault pages are imported automatically on MCP/session start (no manual reindex required).

How it works

What gets remembered

Capture during a session is deterministic: failed commands, failing tests, dependency changes, explicit saves, and the prompts you type. No model watches your tool calls and no "Modified foo.ts" records are stored.

At session end, one small-model call on your gateway reads the transcript and writes a session record: what you were doing, decisions with status, plans, open questions, next steps, and self-contained facts and lessons. The record folds into the repo's handoff page, which is the first thing the next session sees, on any machine and any agent. A second bounded call extracts retro findings (repeated errors, missed known fixes, missing checks) so recurring friction becomes visible instead of being re-lived.

If the end hook never fired (killed terminal, crashed agent), the next session start finds the transcript and writes the record then.

Point Engrm at a model server

engrm ai probe 10.20.0.10        # finds LiteLLM / Ollama / vLLM / LM Studio and lists models
engrm ai use 10.20.0.10:4000     # OpenAI-compatible /v1; add --key=… if it asks
engrm ai roles session_note=extract retro=agent
engrm ai status

Without a gateway, Engrm still captures deterministically and skips the session record.

MCP tools

engrm setup / engrm register also installs a personal Claude Code engrm-memory skill. Natural continuity prompts such as “where are we up to with X?” trigger memory search before repo inspection; users do not need to name Engrm or tell the agent where to look.

CLI

engrm setup                 Local memory + register Claude Code, Codex, Cursor, OpenCode
engrm ai probe|use|roles|status|off
engrm session finalize --session=<id> [--cwd=<dir>] [--agent=<name>] [--force]
engrm status | doctor | register | reindex | dedupe
engrm mesh …                LAN peer sync
engrm dogfood miss|hit|note|report   Retrieval quality ledger

ENGRM_HOME overrides the data directory (~/.engrm); test harnesses use it so they can never touch a live store.

Frozen (not memory-only): Sentinel, packs. Set ENGRM_LEGACY=1 only if needed.

Non-goals

• Sentinel / real-time code audit
• Delivery Review
• Knowledge-pack marketplace
• Team billing as a launch pillar
• Cloud required for core memory (local-first; network is sync only)

Development

bun test
bun run test:acceptance
bun run test:fresh
bun run test:dogfood
bun run test:live    # optional
bun run test:lan     # optional

License

FSL-1.1-ALv2 — see LICENSE.

Documentation

• SCOPE.md · HARNESS.md · ARCHITECTURE.md

Maintainers: node scripts/check-public-docs.mjs