engram-sync

Shared memory for AI coding agents across all your machines. Facts live as markdown in a private git repo you own. Claude Code, Codex, OpenCode, Antigravity and Muse all read the same memory, and every machine pulls and pushes it automatically.

pip install engram-sync
engram init yourname/agent-memory

init takes a GitHub owner/name or any git URL. Create the repo first as an empty private repo. On the first machine init seeds it. On every other machine init clones it. Then init:

1. connects every agent it finds on this machine (details below);
2. schedules a background push every 30 minutes (Windows Task Scheduler, or cron on Linux/macOS);
3. runs the first sync.

Run engram doctor to check everything is wired up.

What lands in each agent

Three skills ship with the package: engram (operate sync), engram-remember (save a fact to the right file) and engram-consolidate (weekly cleanup, conflict repair). Put your own skills in skills/<name>/SKILL.md (or .claude/skills/<name>/SKILL.md) inside the memory repo and every connected agent on every machine gets them on the next pull.

Instructions go between <!-- engram-sync:begin --> and <!-- engram-sync:end --> markers. Your own text around the markers is never touched. A skill folder you created yourself is never overwritten, even if it has the same name as one of engram's, unless you run engram connect --adopt. engram disconnect removes exactly what connect added.

Commands

The memory repo defaults to ~/engram. Use --repo <path> or $ENGRAM_HOME to put it elsewhere.

Memory repo layout

index.md          routing table, loaded into every session (keep under 100 lines)
projects/<x>.md   one file per project, read on demand
global/           preferences and machine facts
inbox/YYYY-MM.md  quick captures, merged out by engram-consolidate
archive/          dormant projects and the consolidate log
skills/           optional: your own skills, shared to every agent
.engram/sync-paths.conf   what syncs automatically

Safety

• Sync commits only the paths in .engram/sync-paths.conf. Anything else in the repo needs a manual commit.
• Each push scans added lines for AWS, GitHub, Slack, OpenAI, Anthropic and Google keys, private keys, JWTs and password=-style strings. On a match nothing is committed and ALERT.md explains the fix. Mark a known false positive with <!-- engram:not-a-secret --> on that line.
• When two machines can't merge (one deleted a file the other edited), the losing machine force-pushes its commits to conflict/<host> on your remote and writes ALERT.md. The next session sees the alert. Saying "consolidate memory" merges the branch back. No commit is ever left only on one machine.
• Git never prompts. Every remote call runs with prompts and credential dialogs disabled and with stall timeouts, so a session never hangs on a password box.

Full rules: docs/sync-contract.md.

Requirements

Python 3.9+ and git on PATH. No other dependencies. Authenticate git to your remote the usual way (GitHub CLI, credential manager or SSH key) before init.

Development

pip install -e .
python -m unittest discover -s tests -t .

License

MIT