Skip to content
grimmerkPublic

About

Version control and two-way sync for your AI coding agent's files: Claude Code's memory, skills and settings, files it edits, and companion docs (notes and translations beside a repo you can't commit to). Each change is a commit named for its session, in a git repo you own, synced across machines. mem + saga, Old Norse for “story” or “history”.

Topics

Resources

Stars

21 stars

Watchers

0 watching

Forks

Repository files navigation

memsaga

Version control and two-way sync for your AI coding agent's files, starting with Claude Code: what it remembers, how you configure it, and anything else you choose.

Website: memsaga.grimmer.io · Try it first · Install (with Claude Code or by hand) · Update · Do you need it? · FAQ · Discussions

memsaga: three sources (Claude Code's config directory in every account, files elsewhere you choose, and content kept only in the repository) become a readable history in a git repository you own, each change named after its session, from fixing a login redirect to restoring CLAUDE.md to Monday's version. The repository syncs both ways between this machine, a private GitHub repository and another machine, and edits made on the web or a phone come back.

Claude Code writes what it learns about you and your projects into Markdown files on your machine (its auto memory), next to your CLAUDE.md instructions and your skills. These files have no history, and they live only on the machine that wrote them. A later session can rewrite a memory, two sessions that edit the same file on one day leave no trace of the earlier version, and a clean-up that merges ten memories into three cannot be undone. (A CLAUDE.md inside a repository is versioned with that repository; your global ~/.claude/CLAUDE.md and the memory files are not.)

memsaga keeps them as history:

① Claude writes or changes a memory, CLAUDE.md or a skill
        │
② when Claude's reply ends (a turn), a memsaga hook copies what changed into a git
  repository you own (the data repository) and commits it, named after the
  conversation
        │
③ with an `origin` remote (on GitHub, for example), the commit is pushed
  there on its own; your other machines pull it, and an edit made on another
  machine or on GitHub reaches the live file (the one Claude Code reads)

When each step runs, and how to change it: Timing.

Status: early, in daily use by its author on macOS; Linux is tested in CI and in a container. Claude Code is the only source today; other agents and sources are on the roadmap.

New to Claude Code's memory? The two kinds, and how a memory gets written

Claude Code keeps two kinds of memory, both plain Markdown files on your machine (Anthropic's docs):

CLAUDE.md Auto memory (Claude Code's own name for it)
Who writes it You, or Claude when you ask ("add this to CLAUDE.md") Claude: when you ask it to remember something, and on its own from your corrections and preferences
Where ~/.claude/CLAUDE.md for every project, and CLAUDE.md in a repository ~/.claude/projects/<project>/memory/: a MEMORY.md index and one file per memory
Loaded The whole file, every session The first 200 lines (or 25 KB) of MEMORY.md every session; each memory file when Claude needs it

Two ways a memory gets written:

you:          Remember that the API tests need a local Redis.
Claude:       writes memory/api_tests.md, and adds a line for it to MEMORY.md
Claude Code:  Saved 1 memory

you:          No, we only deploy on Fridays, from a git tag.
Claude:       decides this is worth keeping, writes memory/deploy_rules.md
Claude Code:  Saved 1 memory

Claude decides what is worth keeping, so not every session saves something. A session next week loads MEMORY.md, sees the line for deploy_rules.md, and reads that file before it answers how to deploy. Claude also reads your skills from ~/.claude/, and Claude Code runs the hooks settings.json points at.

Contents

More documents: FAQ (other ways to keep this history, compared) · docs/architecture.md (for contributors) · docs/two-way-sync.md (design and measurements of two-way sync) · docs/design.md (the design record).

Pictures: the image at the top; a recording in use case 1; a sequence diagram and a recording in use case 10.

What goes into the data repository

memsaga keeps one git repository you own, the data repository, and fills it from three places, told apart by where a file lives:

  1. Claude Code's config directory (~/.claude). What Claude Code reads and writes there: memory, CLAUDE.md, skills, hooks, scripts and (if you want) settings.json, plus folders of your own such as drafts or hand-written mods, once you list them in dirs. They are mirrored without changing where they live or how Claude Code writes them.
  2. Files elsewhere that you choose. A notes file, a plan in your home directory, a dotfile: whoever edits it, you or Claude, the change is committed.
  3. Content that lives only in the repository. It is a normal git repository: add notes, companion documents (your notes, translations or drafts about other repositories), anything else; edit and push from anywhere. memsaga commits what you add and never deletes it.

One repository can hold every Claude Code account and machine you use, and each commit names the conversation that made it.

Do you need memsaga?

Maybe not. If you use Claude Code with one account on one computer, a do-it-yourself setup gets you most of the history:

  1. Turn ~/.claude into a git repository, a folder whose history git keeps (git init).
  2. Add a .gitignore that lets in only what you want kept (memory, CLAUDE.md, skills) and keeps out conversations and credentials.
  3. Add a hook that commits at the end of every reply (a Stop hook).

memsaga does this for you, with nothing to write yourself, and also handles what that setup cannot easily handle:

Do it yourself memsaga
Which files are kept A list you write and keep up to date The files Claude Code reads or runs (CLAUDE.md, memory, skills, subagents, commands, rules, hooks), from Claude Code's own directory reference. Credentials, conversations and caches stay out
Where the history lives In ~/.claude itself, so one git checkout or git clean there, or a merge conflict, changes the files Claude is reading In a normal folder you choose, away from the files Claude is using (by default memories in the folder where you keep code). Its index.md lists every project by its real folder, so it is easy to browse in Finder, an editor or Obsidian
Files outside ~/.claude Not covered Any file you name, such as a plan in your home directory or another tool's config file, whoever edits it; folders of your own inside ~/.claude too (use case 5). Whole folders outside ~/.claude are not supported yet (#20)
An edit made on GitHub, a phone or another computer Comes back through a git pull that writes straight into the files in use; a conflict leaves git's markers in a file Claude reads Brought to the live file for you, keeping the edits of both sides. If both changed the same line, memsaga stops and tells you. Claude is told what changed (use case 10)
More than one account or computer A second account needs a second repository Every account in one repository; another computer picks up changes the next time you use Claude there (use cases 8 and 9)
Which conversation made a change Not recorded, unless your hook adds it Every commit names it, and claude --resume reopens it while Claude Code still keeps the conversation (use case 1)
History from before you started None Rebuilt from the edits recorded in Claude Code's saved conversations (use case 4)
Your own documents about other projects No place for them A note, translation or draft that must not go into the project's own repository (your employer's, say) is filed by project and file under companion/, so a later conversation finds it (use case 7)

Other ways to do this, compared, and the do-it-yourself setup step by step: FAQ.

Quick start

You need macOS or Linux (for Windows, see the FAQ), git and Claude Code. gh (the GitHub command-line tool) is optional, for creating the GitHub repository.

Way What happens
Try it first Look at a week of example history on GitHub, or build it on your machine without touching your own setup
Install with Claude Code Claude Code runs the install steps and asks before each one
Install by hand You run the same steps yourself, one command at a time

A second machine for a data repository you already have? Follow Setting up another machine instead. Running init there would start a second, separate history.

Try it first

To look without installing anything, browse grimmerk/memsaga-example: a data repository with a week of example commits (a bug fix, a memory tidy-up, companion documents, a file added by hand, a restore).

To try the commands on that example, install memsaga (step 1 below), then run demo/setup.sh from a clone of this repository. It builds a fake home directory under /tmp with a Claude Code config, two projects' memory and the same week of history, and never reads or writes your real one; source /tmp/memsaga-demo/env.sh then points memsaga and git at it, in that terminal only. Open a new terminal before you set up your own.

Install with Claude Code

Paste this prompt into Claude Code:

Install memsaga for me. Follow
https://raw.githubusercontent.com/grimmerk/memsaga/main/INSTALL-WITH-CLAUDE.md
and ask me before each step that changes my machine.

Claude checks what you have, then runs the steps of Install by hand and asks before each one, including where the data repository goes. INSTALL-WITH-CLAUDE.md is the file it follows. It also lists the permission prompts seen in a test run: none in auto mode, 11 in manual mode. To read each command before anything runs, install by hand instead.

The same prompt updates or removes memsaga: start it with "Update memsaga for me" or "Uninstall memsaga for me" instead (Updating, Uninstalling).

Install by hand

Run the steps one at a time; each block below is one step.

  1. Install the prebuilt binary (Apple silicon and Intel Macs, Linux on x86_64 and arm64), with the install script or with Homebrew. Other ways to install are further down.

    The install script puts it in ~/.cargo/bin:

    curl --proto '=https' --tlsv1.2 -LsSf \
      https://github.com/grimmerk/memsaga/releases/latest/download/memsaga-installer.sh | sh

    It adds ~/.cargo/bin to your PATH for new terminals only. Open a new terminal, or run source ~/.cargo/env, before the next step.

    Or with Homebrew (macOS or Linux), which puts memsaga on your PATH at once:

    brew install grimmerk/tap/memsaga

    If Homebrew stops with a message about Xcode or the Command Line Tools, that is its own check before it installs anything: update them as it says, or use the install script above, which needs neither.

  2. See where the data repository would go, what would be imported, and how much history can be replayed. Nothing is written:

    memsaga init --dry-run

    Check three things before step 3:

    • Where the data repository goes: by default a folder named memories in the folder where you keep code, for example ~/git/memories. To put it elsewhere, add --repo <path> to memsaga init in step 3; where the data repository goes has the rules.
    • The dry run's root … lines list the Claude Code config folders it found. If one you use is missing (you run Claude Code with CLAUDE_CONFIG_DIR, or a second account), see Which config directories.
    • A project to keep out entirely, for example client work: exclude it now, since what step 3 commits stays in the history. Add a line to ~/.config/memsaga/config.toml with the project's Claude Code directory name, as the dry run lists it. For ~/git/client and every project below it (and any sibling whose name starts with client-): exclude_projects = ["*-git-client", "*-git-client-*"].
  3. Create the data repository, replay the history and import the current state, then register the hooks in each Claude Code config directory. --skills also adds the bundled skills that use cases 3 and 7 use; leave it out if you do not want them. It writes a SKILL.md into the folders memsaga-history, companion-docs and companions under skills/, replacing the SKILL.md of a folder of the same name, so rename one first if you already have it:

    memsaga init
    memsaga install --skills
  4. Optional: a private GitHub repository, so the history is backed up and synced between machines. Any name works; gh needs gh auth login once:

    gh repo create memories --private --source "$(memsaga repo)" --push

    Without gh, create an empty private repository on GitHub, then run git -C "$(memsaga repo)" remote add origin <its URL> and git -C "$(memsaga repo)" push -u origin HEAD.

  5. Check the last sweep, pending changes and push state:

    memsaga status

After the install

Nothing else is needed. Every turn that changed something in scope ends with a commit, and the terminal shows a one-line notice. Once the data repository has an origin remote (optional step 4 above), pushes happen on their own (timing; memsaga push pushes now); without one, the history stays on this machine.

Keep the data repository private. Memory holds whatever Claude learned while working with you, which often includes details of your work. The default scope leaves out ~/.claude.json (where Claude Code keeps its login), credentials and transcripts, and takes settings.json only if you ask. Before each commit, memsaga also checks the lines a change adds for known key shapes (API keys and tokens from Anthropic, OpenAI, GitHub, AWS, Slack, Google, Stripe, npm, GitLab and Hugging Face, and private key blocks). A file with a match is held back: it is not committed, the other files are, and the terminal notice and memsaga status name the file and the line, never the key itself. Once the line is gone, the next commit takes the file. A key in a shape the check does not know still gets through, so keep credentials out of anything you add to files, dirs or extra_files all the same (details). To keep a project's memory out entirely, exclude it before init (step 2 above); excluding it later stops new commits but does not remove what is already in the history.

Other ways to install

  • From source, with Rust's cargo (Rust 1.88 or later): cargo install memsaga --locked from crates.io, or cargo install --git https://github.com/grimmerk/memsaga memsaga --locked for the latest main.
  • Without piping a script into sh: download the archive for your platform from the Releases page and put memsaga on your PATH. On macOS a browser marks the download as quarantined, and the binary is not notarized, so clear the mark once: xattr -d com.apple.quarantine memsaga.

Updating

To update memsaga to a new release:

  1. Get the new binary the way you installed it. With Homebrew: brew upgrade memsaga. With the install script: run step 1 of Install by hand again; it downloads the latest release and replaces ~/.cargo/bin/memsaga. Built from source: add --force to the cargo install line. An archive from the Releases page: replace that binary with the new release's.
  2. memsaga install, with --skills if you installed the bundled skills. It is safe to run again: it updates memsaga's own hook entries in place and adds any hook the new version needs. --skills overwrites the bundled skills' SKILL.md without committing first. If you edited one by hand since Claude's last reply, run memsaga sweep before this step, so your version is in the history and memsaga restore can bring it back.

To let Claude Code do both steps, paste the prompt from Install with Claude Code with "Update memsaga for me" in place of "Install memsaga for me".

memsaga --version shows what is installed. Running sessions need no restart: every hook starts a new process, so the next one uses the new binary. If several machines share one data repository, update them together.

Moving a machine to another install method (to Homebrew, say) needs nothing more: each machine keeps the hook path it registered, even with settings.json synced. Only while another machine that shares it still runs memsaga 0.1.3 or earlier, link and register one path as in Setting up another machine, step 3.

To remove memsaga instead: Uninstalling.

What you can do with it

Use cases 1 to 4 work right after the quick start (3, and 7 below, use the bundled skills from memsaga install --skills). 5 to 7 add files of your own. 8 to 10 are about working in more than one place. 11 is one example of what a full history makes safe to try.

The examples use ~/git/webapp for a project of yours. If you keep code somewhere else, read ~/git as that folder. In the data repository, that project's memory is the folder claude/memory/HOME-git-webapp/ (memory directory names explains the name), and index.md at the top of the data repository lists the folder of each of your projects.

None of them needs you to know git. memsaga restore shows the change and asks before it writes anything, and with the bundled skills you can ask Claude instead: "what did CLAUDE.md say about testing last week?" The git commands below are there for those who want them.

1. See what Claude remembered, and when it changed

Terminal recording on example data: git log of a week of memsaga commits, each named after its session; the Session-Title and Session trailers of the commit that added a memory about the OAuth redirect; git log -S finding the session that removed a rule from CLAUDE.md and the restore that brought it back; the live CLAUDE.md with the rule again.

Every memory file, skill and your global CLAUDE.md gets a normal git history, in the data repository:

cd "$(memsaga repo)"
git log -p -- claude/CLAUDE.md
git log -p --follow -- claude/memory/HOME-git-webapp/MEMORY.md

Each commit says which session changed what, in which directory and account (see commit messages):

[fix login redirect after OAuth] claude:memory:HOME-git-webapp

1 file changed, 4 insertions(+)
A	claude/memory/HOME-git-webapp/auth-flow.md

Event: Stop
Account: claude
Session: 08ad5ab3-28b7-4d51-bfeb-4cd32a95b22c
Cwd: /Users/me/git/webapp
Agent: main
Session-Title: fix login redirect after OAuth

The title and ID work in both directions:

  • From a change to the conversation. The Session: line is the session ID. Its transcript is ~/.claude/projects/<slug>/<session>.jsonl, and claude --resume <session>, run in the Cwd: directory, reopens it.
  • From a conversation to its changes. Everything one session changed: git -C "$(memsaga repo)" log -p --grep 'Session: <session>'. By title, when you remember the topic but not the session: git -C "$(memsaga repo)" log --grep 'Session-Title: .*login'.

Claude Code deletes transcripts after 30 days by default; raise cleanupPeriodDays in settings.json to keep them longer. The commits stay either way.

Three more questions that git answers directly:

  • Why is this line in CLAUDE.md? git -C "$(memsaga repo)" blame claude/CLAUDE.md gives the commit of each line, and that commit's Session: line gives the conversation.
  • When was a sentence added, or removed? git -C "$(memsaga repo)" log -S 'run the tests first' --oneline
  • What changed this week? git -C "$(memsaga repo)" log --since=1.week --stat

You also see changes as they happen. After a turn that committed, the terminal shows one line such as memsaga: 2 files committed (a1b2c3d), so a memory Claude wrote on its own does not go unnoticed. Claude Code prints it as Stop says: memsaga: …: the prefix is Claude Code's, naming the hook that runs at the end of a turn (Stop). reporter = false turns the line off. For one commit per edit instead of one per turn, set granularity = "edit".

The repository is also easy to read on GitHub: index.md lists every project with its real directory, and the memory files already use frontmatter and [[wikilinks]], so the repository opens as an Obsidian vault too.

2. Undo a bad edit or a memory clean-up

memsaga restore copies a file from history back to its live location. It shows the diff first and asks before it writes. Three examples; run one at a time, since each waits for your answer:

memsaga restore claude/memory/HOME-git-webapp/notes.md --at HEAD~3

# any git revision; the live path works too
memsaga restore ~/.claude/CLAUDE.md --at a1b2c3d

# every mirrored file as it was then
memsaga restore --all --at a1b2c3d

A deleted file comes back the same way. --all overwrites the files that differ and never deletes anything.

3. Ask Claude about the history

memsaga install --skills adds the memsaga-history skill to each config directory. Then questions such as "what did CLAUDE.md say about testing last week?" or "when did this memory change, and why?" are answered from the history: the skill knows the repository layout and the git commands, and it restores a file only after you say yes.

4. Start with the history you already have

The first memsaga init reads your Claude Code session transcripts and replays the edits they record as dated commits, so the repository starts with weeks of history instead of a single snapshot. memsaga init --dry-run shows how much can be replayed. (Transcripts only reach back as far as Claude Code keeps them, 30 days by default.)

5. Version any file Claude edits for you

Claude often writes files outside its config directory: a plan in your home directory, notes about a repository that you do not want to commit to it, a config file it fixed. List each such file in extra_files, and memsaga commits every change to it at the end of the turn, whoever made it:

extra_files = ["~/notes/plan.md", "~/.config/starship.toml"]

The copy is stored under extra/ by its real path, is never deleted by memsaga, and gets edits made elsewhere like any other file (use case 10). For a group of files, make a folder under the config directory (for example ~/.claude/drafts/) and add it to dirs. The same goes for hand-written Claude Code mods: add "mods" and their source is versioned and synced like your skills, and add "mods/*/.claude-plugin/types" (the folder the mod engine regenerates) to exclude_paths. Setting either key replaces its default list, so start from the defaults in configuration and append:

dirs = ["skills", "commands", "agents", "agent-memory", "rules", "output-styles",
        "themes", "workflows", "hooks", "scripts", "drafts", "mods"]
exclude_paths = ["skills/synced", "skills/.trash", "mods/*/.claude-plugin/types"]

Whole folders outside the config directory are not supported yet (#20); until then, list their files one by one, or keep the folder under the config directory and add it to dirs, as above. A folder listed in extra_files is skipped, and memsaga status and memsaga config say so.

6. Add your own files to the repository

The data repository is a normal git repository, so it can hold anything else you want versioned next to your agent's files: reference notes, prompts you reuse, a log of decisions. Put files at the top level, outside the account folders such as claude/ (for example in a manual/ folder). The next sweep commits them, or commit them yourself; memsaga never deletes what it did not copy. You can also commit and push from another machine or edit in GitHub's web editor. An edit to a mirrored file made in the repository, say to claude/CLAUDE.md, is not overwritten: it goes to the live file (use case 10).

7. Companion docs: notes beside a repository, never committed to it

Some documents belong with a repository but must not be committed to it: a translation of its docs, your annotated copy, a draft written before the source exists, a note about the repository as a whole. Ask Claude for one in any language, and the companion-docs skill puts it at <data repository>/companion/<repo>/<path>, keyed by the source file's path (a note goes under companion/<repo>/_notes/), so it is versioned and synced with the rest of your memory. Before Claude summarises or translates a document, the skill has it check for an existing companion. memsaga companions [repo], or /companions in a session, lists them with the status and source recorded in each one's frontmatter. That frontmatter uses the fields of the Open Knowledge Format (OKF, a Google Cloud specification for markdown knowledge files): type, title and description, a translation's source file and commit in sources, who wrote it in generated, and status (draft, stable or deprecated), so any tool that reads OKF can read a companion. Memory files, skills and CLAUDE.md keep their own formats. The example repository has three of them.

8. Two Claude Code accounts

If you run more than one account, each with its own config directory (for example ~/.claude and ~/.claude-work through CLAUDE_CONFIG_DIR), list each as a root in ~/.config/memsaga/config.toml:

[[roots]]
path = "~/.claude"
label = "claude"

[[roots]]
path = "~/.claude-work"
label = "claude-work"

Each gets its own subtree in the repository (claude/, claude-work/), and each commit's Account: line says which account made the change. Files the second account shares through symlinks (a common pattern for CLAUDE.md and skills/) are stored once, as relative symlinks.

CodeV, a macOS launcher for Claude Code accounts, keeps a list of accounts. When your config names no roots, memsaga reads that list if it exists, and otherwise uses ~/.claude.

9. Two machines

Clone the data repository on the second machine and restore from it (the steps are in setting up another machine). After that both machines commit and push. A push that GitHub rejects because the other machine pushed first merges the other machine's commits and pushes again, and their edits reach your live files as described in use case 10.

Everything in scope travels this way, not only memory: a skill, hook or script written on one machine, and a hand-written Claude Code mod once its folder is in dirs, reaches the other machine's disk at its next session start, or a prompt or two later in a session already open there. Your global CLAUDE.md stays the same on both.

A project shares its memory between machines when it sits at the same path relative to the home directory on both, for example ~/git/webapp, even when the user names differ (see memory directory names).

10. Edit from anywhere

You can fix a memory file in GitHub's web editor, on a phone, on another machine, or by hand in the local clone. memsaga does not overwrite such an edit. It brings it to the live file:

Sequence: you edit and commit a memory file in GitHub's web editor. At the next session start or prompt, the memsaga hooks ask GitHub whether origin moved (at most once a minute); it did, so they merge origin into the data repository, write the new version to the live file (merging if both sides changed), and send Claude a notice with the changed lines. Claude reads the file again before using it.

In short:

  1. When a session starts, and at each prompt, memsaga asks GitHub whether the repository moved.
  2. If it moved, memsaga merges the change and writes it to the live file. Edits made on both sides are kept; when both sides changed the same lines, the file is left alone and you are told.
  3. Claude gets a short notice with the changed lines, so it does not answer from the copy it loaded earlier.
  4. Before Claude writes a file memsaga keeps, memsaga asks again, so the edit is not built on an old copy.

A real session (example data): just before it started, deploys.md was edited on GitHub to say production deploys every Friday. Asked how webapp deploys, Claude reads the file again and answers from the new text. (The notice under the reply lists commits from earlier turns: it runs before this turn's commit is written; see #41.)

Claude Code session on example data: the user asks how webapp deploys to production; Claude reads deploys.md and answers that production deploys every Friday from a git tag, the text edited on GitHub just before the session; the memsaga Stop notice lists commits from earlier turns.

All of this happens inside Claude Code sessions. Run it by hand when no session will do it for you:

  • Before you use a machine that has been idle, or before editing its live files outside Claude Code: memsaga sync (both directions) or memsaga pull (only inbound).
  • To push right away, instead of waiting for the throttle or the end of the session, or when those pushes are turned off: memsaga push.
  • When a sync reports a conflict (both sides changed the same lines): see When something looks wrong.
  • When setting up another machine: see Setting up another machine.

How often each step runs, and what Claude Code waits for: timing. What happens to a write that would replace text that just arrived: two-way sync.

11. Let Claude reorganise its memory, safely

Memory grows by small additions: facts repeat across files, old ones go stale, a MEMORY.md index drifts from the files it lists. Asking Claude to clean that up is risky when the only copy is the live one. With every version kept, it becomes a routine you can run boldly, a "dream" pass over what was learned:

  1. Now and then, by hand or on a schedule, start a session with a prompt such as "read every file under ~/.claude/projects/*/memory/, merge duplicates, drop what is no longer true, and keep MEMORY.md in step with the files".
  2. Its edits land as ordinary commits, marked with that session's ID and title (use case 1). Review them like any change: git -C "$(memsaga repo)" log -p --grep 'Session: <id>'.
  3. Keep what helps. Undo the rest one file at a time with memsaga restore, or everything with memsaga restore --all --at <commit before the pass>. --all never deletes, so a file the pass created stays until you remove it.

The same holds for any bold edit: a rewrite of CLAUDE.md, a skills refactor, a new hook. Try it, read the diff, keep it or roll it back.

What memsaga does not cover, and what to use instead

What Why memsaga leaves it What to use instead
Session transcripts Large, and mostly the content of your work rather than configuration Raise cleanupPeriodDays in settings.json so Claude Code keeps them longer. To search or archive them, use a transcript indexer such as funes or fable
Plugins installed from a marketplace They are packages you can install again, not files you wrote Install them again; with settings.json mirrored (opt-in, files), its enabledPlugins list records which ones
Hand-written Claude Code mods Not in the default scope Add "mods" to dirs (use case 5) to version and sync them; give a mod you share or develop seriously its own git repository too, since one commit per turn is a backup, not a development history
Credentials, OAuth tokens, ~/.claude.json Secrets and account state must never enter a repository. A file in scope whose new line looks like a key is held back Your system keychain or a password manager
settings.json keys that change all the time (model, effortLevel) Claude Code rewrites them on every /model and /effort Nothing: memsaga leaves them out of the repository and keeps each machine's own values (settings_ignore_keys)

How it works

  • Hooks. memsaga install registers memsaga in each config directory's settings.json. PostToolUse marks a turn that wrote a file, Stop copies and commits at the end of the turn, and SessionEnd pushes. SessionStart, UserPromptSubmit and PreToolUse bring in edits made elsewhere (use case 10).
  • Mirror. The repository holds copies. Claude Code keeps reading and writing its own files in place; memsaga writes live files only when you restore, or when an edit made elsewhere arrives.
  • Cost. A turn that changed nothing in scope costs a check of modification times. A turn that did costs a copy and a commit, well under a second, and runs in the background. Asking GitHub whether the repository moved costs about half a second (timing).
  • Safety. One lock serialises concurrent sessions. A hook never fails a turn: errors go to a log and to memsaga status.

More: docs/architecture.md.

Timing

When memsaga commits, pushes and checks for edits made elsewhere. Without an origin remote, memsaga uses no network: it commits, and an edit you make by hand in the data repository still comes in, at the next prompt or before Claude reads or writes that file.

What When How to change it
Commit At the end of each turn that changed a file in scope, in the background granularity = "edit": one commit per Write or Edit instead
Push At the end of a turn, at most once every ten minutes. A push that falls inside those ten minutes is not dropped: it runs when they are up. When a session ends, it pushes right away, unless push_on_session_end is off push_min_interval_secs (default 600; 0 turns the end-of-turn push off), push_on_session_end (default true); memsaga push pushes now
Check GitHub for edits made elsewhere When a session starts (Claude Code waits for the answer, about half a second). At each prompt, and when Claude reads a file memsaga keeps, the check runs in the background and its answer is used from the next prompt on. At most once a minute for the whole machine memsaga sync or memsaga pull checks and brings edits in now
Check again before a write Before Claude writes or edits a file memsaga keeps, unless the last check is less than ten seconds old. Claude Code waits for it —
Bring an edit in Right after the check at session start. Otherwise, once a check has found it: at the next prompt, or before Claude reads or writes that file. It is merged into the live file before Claude uses it, and a session that already read the old text gets a notice —

When something looks wrong

  • memsaga status shows the last sweep, the push state (a failed or deferred push, and why), files waiting to come in from elsewhere, and a missing config file. It also lists where this machine differs from the repository: files it never had (kept, not deleted), a folder where the repository has a link (nothing under it is mirrored, so nothing is written through the link), folders the repository has that this machine's config does not mirror, and scripts that settings.json runs but this machine lacks, and files held back because a new line looks like a key (if a file is held back).
  • A hook never stops a turn. Its errors go to <data repository>/.git/memsaga/memsaga.log, and every sweep, push and merge to events.jsonl next to it.
  • memsaga diff shows what the next sweep would commit; memsaga sweep commits now.
  • An edit from elsewhere that conflicts with yours waits, and memsaga sync reports it. Pick a side with memsaga sync --take live <path> or --take repo <path>, or edit the live file and run memsaga sync again.
  • To stop, memsaga uninstall removes the hooks. The repository and its history stay.
  • Questions and ideas go to GitHub Discussions; a bug goes to Issues.

Reference

Commands

Command What it does
memsaga init [--dry-run] [--repo <path>] [--no-backfill] Create the data repository, replay history from session transcripts, import the current state; records the location in the config file. --dry-run only prints the location, what would be imported and how much can be replayed
memsaga status [--json] Last sweep, pending dirty marker, push state (including a failing or deferred push), a missing config file, where this machine differs from the repository (files it never had, a folder where the repository has a link, folders its config does not mirror, missing hook scripts), recent events; --json prints the same as one object for scripts and tools. Read-only
memsaga log [-n <count>] Recent commits
memsaga diff [--stat] What the next sweep would commit (refreshes the mirror, commits nothing)
memsaga restore <path> [--at <rev>] [-y] Copy one file from history back to its live location, diff first
memsaga restore --all --at <rev> [--prune] [-y] Every mirrored (in-scope) file of every root as it was at <rev>: overwrites what differs, never deletes, recreates links as they are (never writes through one), keeps the live settings_ignore_keys; shows the diffs, one confirmation. Lists live files in scope that <rev> does not have; --prune moves them to <data repository>/.git/memsaga/stale/<time>/ instead of leaving them. Before asking, also names folders the repository has that this machine's config does not mirror, and scripts settings.json runs that this machine lacks
memsaga sweep Mirror and commit now
memsaga push Push to origin now (pushes also happen on Stop, throttled, and on SessionEnd); a push rejected because origin moved merges origin first
memsaga sync [--take live|repo <path>] Both directions: commit live changes, merge origin, bring repository-side edits to the live files, commit, push
memsaga pull [--check] [--path <file>] Inbound only (what the hooks run); --check asks whether origin moved, throttled across sessions
memsaga paths Claude Code's project directory names (as in ~/.claude/projects/) and the real folders they stand for
memsaga config The effective configuration
memsaga repo The data repository's path and nothing else, for commands such as cd "$(memsaga repo)" or open "$(memsaga repo)"; fails before init
memsaga companions [repo] List companion documents (status, path, source); /companions in a session prints the same
memsaga install [--skills] [--skill <name>] [--root <dir>] [--no-hooks] Register the hooks in each config directory (or only the --root ones); --skills also writes the bundled skills (memsaga-history, companion-docs, companions), --skill one of them; --no-hooks leaves settings.json alone
memsaga uninstall [--root <dir>] Remove the hooks (from each config directory, or only the --root ones): every hook entry whose command contains memsaga, including one of your own
memsaga backfill Replay session transcripts into dated commits; init does this once

Paths for restore can be repository-relative (claude/memory/<name>/x.md) or the live path. A shorter command name is one alias away: alias mem=memsaga.

What is mirrored

Per config directory (root), by default, what you write there that Claude Code reads (its directory reference): CLAUDE.md, keybindings.json, skills/, commands/, agents/, agent-memory/, rules/, output-styles/, themes/, workflows/, and every non-empty projects/<slug>/memory/. Also hooks/ and scripts/, which Claude Code does not read itself but which hold what settings.json points at by convention. A folder you add yourself, such as drafts/ or hand-written mods/, goes in dirs. settings.json is opt-in (files = ["CLAUDE.md", "keybindings.json", "settings.json"]); the repository stores it without the keys Claude Code rewrites all the time (settings_ignore_keys) and with memsaga's own hook commands in one form, and each machine keeps its own values of both. With settings_ignore_keys = [] the file is stored as it is, hook paths included. Never: transcripts, ~/.claude.json, caches, file-history, plugins, and Claude Code's own synced skills under skills/synced/ and skills/.trash/.

Repository layout:

<data repository>/
  claude/CLAUDE.md
  claude/skills/…  claude/hooks/…  claude/scripts/…
  claude/memory/<name>/{MEMORY.md, *.md}   <name>: see the next section
  claude-work/…                      second account; shared files stay symlinks
  index.md                           generated table of every project
  paths.json                         memory name → real working directory (~ for home)
  memsaga/config.toml                this config file, mirrored automatically
  extra/home/…  extra/root/…         extra_files, by their real path
  companion/  manual/  …             yours: committed, never deleted by the tool

Memory directory names

A project's memory directory is named after its path. Claude Code's own name (the "slug") is the absolute path with every non-alphanumeric character replaced by - (/Users/me/git/webapp → -Users-me-git-webapp). In the repository, a project under the home directory drops the home and starts with HOME (HOME-git-webapp), so machines with different homes (another user name, Linux's /home/...) share one directory per project. Anything outside home keeps Claude Code's name.

One exception: if another directory on the machine encodes like a path under home (/Users/me-old next to /Users/me), memsaga cannot tell them apart and keeps Claude Code's names on that machine.

Configuration

~/.config/memsaga/config.toml. Every key has a default, and memsaga config prints the effective values.

# where init put it (example); `memsaga repo` prints yours
repo = "~/git/memories"
files = ["CLAUDE.md", "keybindings.json"]
dirs = [
  "skills", "commands", "agents", "agent-memory", "rules",
  "output-styles", "themes", "workflows", "hooks", "scripts",
]
memory = true                    # each project's memory/ folder
# file names never copied; *.codev-* are CodeV's backup and temporary files
exclude = ["*.codev-bak*", "*.codev-tmp-*", ".DS_Store", "__pycache__"]
# left out of the mirrored settings.json: Claude Code rewrites them on
# every /model and /effort
settings_ignore_keys = ["model", "effortLevel", "modelSettings"]
exclude_projects = []            # slug globs
exclude_paths = ["skills/synced", "skills/.trash"]   # root-relative subtrees
# single files outside every root, e.g. "~/.config/codev/accounts.json"
extra_files = []
granularity = "turn"             # or "edit": one commit per Write/Edit
reporter = true                  # one-line notice in the terminal after a commit
# at most one push per interval on Stop; a throttled push is deferred to the
# end of the window, not dropped. 0 disables pushes on Stop
push_min_interval_secs = 600
push_on_session_end = true
# hold back a file whose new lines look like a key (see "If a file is held back")
scan_secrets = true
# fingerprints from the notice, or repository paths, the check lets through
allow_secrets = []

[[roots]]
path = "~/.claude"
label = "claude"

Where the data repository goes

init creates a folder named memories inside the first of ~/git, ~/code, ~/src, ~/Projects and ~/dev that exists (for example ~/git/memories); when none of them exists, it creates ~/memories. An existing memsaga repository named memories in one of those places is used first. It records the choice as repo in the config file, so it never moves. memsaga init --repo <path> puts it anywhere else, and init --dry-run shows the choice first. A folder of that name that already holds something else is never taken over: init stops and asks for --repo. A git repository you name yourself, such as a fresh clone of an empty GitHub repository, is used as it is. Until init has run, the hooks and every other command leave all folders alone. memsaga repo prints the path, and the commands in this README use it, so they work wherever yours is.

Which config directories

memsaga mirrors each Claude Code config directory it knows (a root). Without [[roots]] in the config file, it takes the account list of CodeV (~/.config/codev/accounts.json) if you use it (that list includes ~/.claude), and otherwise ~/.claude.

That search does not read CLAUDE_CONFIG_DIR, since hooks run in every account's sessions and each would see different roots. If you run Claude Code with CLAUDE_CONFIG_DIR set, run init where it is set (a terminal that exports it, or a Claude Code session using it): init adds that folder and records all roots as [[roots]] in the config file, so every session sees the same ones. It does so only when the folder exists, is not already a root, and the config file has no roots key (not even roots = []). The root … lines of init --dry-run show the result.

To list roots yourself, write them before init. Listing roots turns off the automatic search, so list ~/.claude too if you also use it:

[[roots]]
path = "~/my-claude-config"   # the folder CLAUDE_CONFIG_DIR points to
label = "claude"

# only if you also use ~/.claude; each root needs its own label
[[roots]]
path = "~/.claude"
label = "claude-default"

memsaga install, memsaga status and memsaga config warn when CLAUDE_CONFIG_DIR names a folder that is not a root, and print the lines to add. A second account set up without CLAUDE_CONFIG_DIR in the shell where you run init (for example ~/.claude-work) is not found either: list it as in Two Claude Code accounts.

If the config file disappears

If the config file disappears while the data repository still holds its mirrored copy, memsaga runs on its defaults: fewer files are mirrored, and copies of files that drop out of scope are left in the repository. The reporter prints a warning with the restore command after every turn until the file is back.

If a file is held back

Before a commit, memsaga reads the lines the change adds (not lines already in the history; the whole file only when those lines may be part of a private key, which spans several lines) and looks for key shapes with a fixed prefix: Anthropic and OpenAI API keys, GitHub, GitLab, npm, Slack and Hugging Face tokens, AWS access key IDs, Google API keys, Stripe live keys, and private keys (a -----BEGIN … PRIVATE KEY----- line followed by the key itself; the line alone, as a constant in code, does not count). The list is a subset of gitleaks' rules, chosen for few false alarms; generic patterns such as password= or JSON Web Tokens are left out. Test keys in code (xoxb-1234… in a test file) look the same as real ones, so a file of copied code or data can be held too; mark it with allow_secrets as below.

A file with a match is held back. What happens then:

  1. The other files of that turn are committed as usual.
  2. The held file is not committed. memsaga's own copy of it in the data repository goes back to its last committed version, so nothing waits half done; a file you wrote in the repository yourself (manual/, a hand edit) is left exactly as it is.
  3. The terminal notice names the file, the line, the kind of key and a fingerprint (a short hash of the match); the end-of-turn notice says this once per held set, and memsaga sweep or sync print it each time they hold the file. memsaga status and status --json (held) list it as long as it is held. The key itself is never printed or logged.
  4. Each later turn checks again. Once the line is gone, the file is committed and the notice says it is no longer held back.
  5. If a sweep cannot take a held file out of the commit (a file name that is not UTF-8, for example), it commits nothing that turn rather than risk the key; the notice says "nothing was committed" and memsaga status shows why, until a later turn gets past the check. init and memsaga backfill stop with that error instead; replay groups committed before it stay, and each of those passed the check.

When the match is not a secret, add memsaga:allow-secret anywhere on that line (for a private key, on its -----BEGIN line), or, in a file that cannot carry a comment (settings.json), add the fingerprint to allow_secrets in the config file. A repository path in allow_secrets ("claude/notes.md") skips the check for that file, and scan_secrets = false turns it off. memsaga diff leaves held files out of the patch it prints, init leaves out any old version it replays from transcripts that holds a key, and a session title that holds one is left out of the commit message.

A key in settings.json's env keeps the file held until the key moves out, for example to your shell profile or a password manager. Edits that reach the data repository through origin (another machine, GitHub's web editor) are already in that history, so the check does not apply to them.

Two-way sync

An edit made outside the live files (in GitHub's web editor, on another machine, or by hand in the local clone) is not overwritten by the next sweep. It waits on a list (memsaga status shows it) until it is brought to the live file. When only the repository changed, its version is written; when both sides changed different lines (or made the same change), the texts are merged; conflicting edits to the same lines are left alone and reported (when something looks wrong says how to settle one). A file deleted in the repository is deleted live when the live file was unchanged. The other way round, a live file counts as deleted only on a machine that has had it: a file the repository has but this machine never had (a fresh clone, a folder another machine added to the config) is kept, and memsaga status lists it.

Inside Claude Code sessions, the hooks of use case 10 do this on their own, at the moments in timing. Before a Write or Edit, a change they find is brought in first: a Write that would replace text that just arrived is refused, and Claude is told to read the file again; a change that cannot be merged is refused and left to you.

Design and measurements: docs/two-way-sync.md.

Commit messages

The subject is [<session title>] <areas>, for example [fix login redirect after OAuth] claude:memory:HOME-git-webapp. A title longer than 32 characters is cut there and ends in ..., so the subject stays within 72; the Session-Title: line keeps the whole title. The other lines: Event: (the hook or command), Account: (from CLAUDE_CONFIG_DIR), Session: (the session ID), Cwd: and Agent:. The prompt text is never copied into a commit. With no session title, the subject starts with what made the commit instead: Stop: (a session with no title yet), backfill: (history replayed from transcripts, which keeps each edit's session ID and folder), import: (the snapshot init takes), sync: or manual:. A commit made by a command you run yourself, such as memsaga sync, belongs to no session, so Session: and Cwd: read none; the merge memsaga makes when origin moved is just sync: merge origin/<branch>.

Uninstalling

For the usual setup (one config directory, ~/.claude, and the install script), these steps remove everything memsaga added. Run them one at a time.

  1. Remove the hooks from every config directory; Claude Code stops committing. This removes every hook whose command contains the word memsaga, so rename a hook of your own that does first:

    memsaga uninstall
  2. Remove the binary, the config file with the install script's receipt, and the file the install script wrote for the fish shell:

    rm ~/.cargo/bin/memsaga
    rm -r ~/.config/memsaga
    rm -f ~/.config/fish/conf.d/memsaga.env.fish
  3. If you ran memsaga install --skills, remove the bundled skills. If you added files of your own to these folders, move them out first; rm -rI asks once before it removes anything:

    rm -rI ~/.claude/skills/memsaga-history ~/.claude/skills/companion-docs \
      ~/.claude/skills/companions
  4. If you no longer need it, remove the copy of settings.json that memsaga install took before its first change. rm -i asks first:

    rm -i ~/.claude/settings.json.memsaga-bak
  • Another config directory (a second account such as ~/.claude-work, or a folder CLAUDE_CONFIG_DIR points to): repeat steps 3 and 4 with its path. Skip the skills when its skills is a link to ~/.claude/skills.

  • Installed with Homebrew: in step 2, run brew uninstall memsaga, and remove ~/.cargo/bin/memsaga only if you linked it there (Setting up another machine, step 3). Skip the fish file and the ~/.cargo clean-up below; Homebrew wrote neither. brew untap grimmerk/tap also removes the tap if nothing else of yours comes from it.

  • A binary from a downloaded archive: delete the copy you put on your PATH. Built with cargo: cargo uninstall memsaga.

  • The install script also added the line . "$HOME/.cargo/env" to the shell startup files it found (on macOS usually ~/.zshenv and ~/.profile). If nothing else you use lives in ~/.cargo (no Rust toolchain, no other cargo install tools), remove that line and the folder:

    for f in ~/.zshenv ~/.zshrc ~/.profile ~/.bashrc ~/.bash_profile ~/.bash_login; do
      [ -f "$f" ] && sed -i.bak '/\.cargo\/env/d' "$f"
    done
    rm -r ~/.cargo

    sed -i.bak keeps the previous version of each file as <file>.bak.

None of this touches the data repository or its copy on GitHub: they are your history. Delete them yourself only if you no longer want it. Claude Code can also do the steps above, asking before each one: paste the prompt from Install with Claude Code with "Uninstall memsaga for me" in place of "Install memsaga for me".

Setting up another machine

Tested with the same user name and the same folder layout on both machines:

  1. Install Claude Code and sign in once, so ~/.claude exists. Create the directory of every other account in your config (for example ~/.claude-work); a root that does not exist is skipped, with a count.

  2. Clone the data repository to the same path as on the first machine (memsaga repo prints it there), and copy its config. Do not run memsaga init on the new machine: it would commit its empty state on top of your history.

    D=~/git/memories        # the path memsaga repo prints on the first machine
    git clone git@github.com:<you>/memories.git "$D"   # or: gh repo clone <you>/memories "$D"
    mkdir -p ~/.config/memsaga && cp "$D/memsaga/config.toml" ~/.config/memsaga/config.toml
  3. Install memsaga (step 1 of Install by hand), any way: each machine keeps the path of its own binary in its hook commands, even with settings.json synced (the repository stores memsaga's hook commands in one form, and each machine's path is put back when the file arrives). memsaga 0.1.3 and earlier synced the path itself, so a machine pulling another machine's path ran hooks pointing at nothing (#55). While a machine on 0.1.3 or earlier shares the repository, give every Homebrew machine the install script's path, and register it in step 6 with --bin '$HOME/.cargo/bin/memsaga':

    mkdir -p ~/.cargo/bin && ln -sf "$(brew --prefix)/bin/memsaga" ~/.cargo/bin/memsaga
  4. memsaga restore --all --at HEAD: read the list and the diffs, answer n; then run it again with --yes. Files get their content, executable bits and commit time back; links that share files between accounts are recreated, and so are links to another tool's folder, as they are, even when that folder is not on this machine yet. Nothing is deleted. Before it asks, the restore also names folders the repository has that your config does not mirror (copy the config, step 2), and scripts that settings.json runs but this machine lacks.

  5. Verify: memsaga sweep --event verify should report no changes; then memsaga diff --stat should print no changes since the last commit. If the verify sweep commits anything, look at it with git -C "$(memsaga repo)" show --stat before you go on, and see the next paragraph.

  6. Register the hooks, with --skills if you use the bundled skills: memsaga install --skills. On a Homebrew machine linked as in step 3, because a machine on 0.1.3 or earlier shares the repository: memsaga install --skills --bin '$HOME/.cargo/bin/memsaga' (the single quotes keep $HOME for the shell that runs the hook). From here on, Claude Code sessions on this machine commit and push.

A machine that ran memsaga before (an older data repository or config): move the old data repository aside rather than deleting it, then do steps 2 to 6. Live files from before may still be there after the other machine removed or moved them: a memory file moved to another project, a folder that became a link. restore --all lists them as not in the repository and leaves them, since on any other machine such a file may simply be new; add --prune to move them to <data repository>/.git/memsaga/stale/<time>/ (nothing is deleted), which also lets a link come back where an old folder stood. Until then a folder where the repository has a link is left alone by every sweep, and memsaga status lists it.

If settings.json is in your files (it is not by default), restoring it also registers the hooks, and step 6 finds them already there. The hooks may run scripts from outside memsaga's scope (another tool's status hook, for example); restore and memsaga status name any that this machine lacks. Mirror such a script from the machine that has it (files or dirs for a path in a config directory, extra_files for one elsewhere), or install the tool that writes it. Do not remove the hook on the machine that lacks it: two-way sync would remove it on every machine.

Tests

cargo test. What the tests cover, and how the code is organised: docs/architecture.md.

Roadmap

Plans, not promises:

  • More sources: other coding agents that keep memory or instruction files on disk (Codex first: its opt-in memories under ~/.codex/memories/, AGENTS.md and skills), whole folders outside the config directory (#20), and remote knowledge bases, such as a server hosting a tree of markdown documents.
  • A Claude Code mod that shows the sync state in the status line, and later runs the hook work inside Claude Code instead of a new process per event.
  • Folder aliases for machines whose project folders differ below home (~/code on one, ~/git on the other).
  • Files that belong to one machine only, kept per machine in the repository.

The name

mem, for memory, and saga, from Old Norse for "story" or "history", the word for the medieval Icelandic narratives that followed people and events across generations. A repository of memory that keeps every version is the story of how that memory came to be, one change at a time.

License

MIT

About

Version control and two-way sync for your AI coding agent's files: Claude Code's memory, skills and settings, files it edits, and companion docs (notes and translations beside a repo you can't commit to). Each change is a commit named for its session, in a git repo you own, synced across machines. mem + saga, Old Norse for “story” or “history”.

Topics

Resources

Stars

21 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂