
memsaga
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 t…
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up memsaga (release-binary project) into my current project. Found on https://claudeers.com/memsaga Repo: https://github.com/grimmerk/memsaga Homepage/docs: https://memsaga.grimmer.io Detected install method: release-binary → inspect the README Category: devtools. Platforms: cli, api, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/grimmerk/memsaga/releases
git clone https://github.com/grimmerk/memsaga
// compatibility
| Platforms | cli, api, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Rust |
memsaga
Version control and two-way sync for the files your AI coding agent works with: what it remembers, how you configure it, and anything else you choose.
Website: memsaga.grimmer.io · Install (with Claude Code or by hand) · Do you need it? · FAQ · Discussions
How Claude Code remembers
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.
Auto memory and your global ~/.claude/CLAUDE.md have no history, and they
live only on the machine that wrote them (a CLAUDE.md inside a repository is
versioned with that repository). A later session can rewrite
deploy_rules.md, 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.
memsaga keeps them as history:
① Claude writes or changes a memory, CLAUDE.md or a skill
│
② at the end of the turn (by default; it can commit after each edit
instead), a memsaga hook copies what changed into your data repository
and commits it, named after the conversation
│
③ with an `origin` remote (on GitHub, for example), it is pushed there: by
default at most once every ten minutes and at the end of a session, or
now with `memsaga push`; your other machines pull it, and an edit made on
another machine or on GitHub reaches the live file
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:
- 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. They are mirrored without changing where they live or how Claude Code writes them. - 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.
- 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.
Each commit names the session that made the change, by title and by ID, so you can go from any change back to the conversation that caused it, and from a conversation to everything it changed. One repository can be shared by several machines and Claude Code accounts; an edit made in one place (another machine, GitHub's web editor, a phone) reaches the live files everywhere else.
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. Contributor notes: docs/architecture.md.
Two-way sync: docs/two-way-sync.md. Design record:
docs/design.md.
Contents
- Do you need memsaga?
- Quick start: with Claude Code or by hand
- What you can do with it
- Claude Code's config directory
- Files elsewhere, and content only in the repository 5. Version any file Claude edits for you 6. Add your own files to the repository 7. Companion docs: notes beside a repository, never committed to it
- Everywhere you work 8. Two Claude Code accounts 9. Two machines 10. Edit from anywhere
- Going further 11. Let Claude reorganise its memory, safely
- What memsaga does not cover, and what to use instead
- FAQ: other ways to keep this history, compared
- How it works
- When something looks wrong
- Reference: commands, what is mirrored, memory directory names, configuration, two-way sync, commit messages, updating, uninstalling, setting up another machine
- Tests
- Roadmap
- The name
Pictures: the image at the top (where files come from, and where the history goes), and a sequence diagram in use case 10 (what happens when a file changed elsewhere).
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:
- Turn
~/.claudeinto a git repository, a folder whose history git keeps (git init). - Add a
.gitignorethat lets in only what you want kept (memory,CLAUDE.md, skills) and keeps out conversations and credentials. - Add a hook that commits at the end of every reply (a
Stophook).
memsaga does this for you, out of the box. There is no list or hook to write
yourself: it already knows which files Claude Code reads or runs (CLAUDE.md,
memory, skills, subagents, commands, rules, hooks), following Claude Code's own
directory reference, and it leaves out credentials, conversations and caches.
It also handles what the do-it-yourself setup cannot easily handle:
- A separate repository, away from the files Claude is using. In the
do-it-yourself setup, Claude Code's own folder is the repository, so a
single git command run there (
git checkout,git clean) or a merge conflict changes the files Claude is reading. memsaga keeps its copies in a normal folder you choose (by defaultmemoriesin the folder where you keep code), not in the hidden~/.claude, with anindex.mdthat lists every project by its real folder, so it is easy to browse in Finder, an editor or Obsidian. - Files you choose, even outside Claude Code's folder. Beyond the files
Claude Code uses, which are covered by default (above), a folder you create
in
~/.claudeyourself, such as~/.claude/drafts/, takes one line indirs. Outside~/.claude, name each file inextra_files, such as a plan in your home directory or another tool's config file, and every change to it is committed, whether you made it or Claude did (use case 5). Whole folders outside~/.claudeare not supported yet (#20). - Edits from anywhere, and more than one account or computer. You can fix
a memory in GitHub's web editor, on a phone, or on another computer. In the
do-it-yourself setup, bringing such an edit back is a
git pullthat writes straight into the files in use, and a conflict leaves git's markers in a file Claude reads. memsaga brings the edit to the live file for you: it keeps the edits made on both sides, and if both changed the same line, it stops and tells you. It also tells Claude what changed. Every account lives in one repository, and another computer picks up changes the next time you use Claude there. - Which conversation made each change. Every commit names the conversation
behind it, and
claude --resumereopens that conversation as long as Claude Code keeps it: 30 days after its last use, unless you raisecleanupPeriodDays. - History from before you installed it. memsaga rebuilds it from the edits recorded in those same saved conversations.
- Your own documents about other projects. Some documents are about a
project but must not go into its repository, for example notes on your
employer's code. Ask Claude for one (a note, a translation of its docs, or a
draft) and it is kept in memsaga's repository under
companion/, filed by the project and file it is about, so a later conversation finds it again. memsaga calls these companion documents (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, git and Claude Code. gh (the GitHub command-line
tool) is optional, for creating the GitHub repository. There are two ways to
install: let Claude Code do it, or
install by hand. Both run the same steps.
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.
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.
Install by hand
Step 1 installs a prebuilt binary (Apple silicon and Intel Macs, Linux on
x86_64 and arm64). To build from source instead, 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.
Rather not pipe 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.
Run the steps one at a time; each block below is one step.
-
Install the prebuilt binary into
~/.cargo/bin:curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/grimmerk/memsaga/releases/latest/download/memsaga-installer.sh | shThe installer adds
~/.cargo/binto yourPATHfor new terminals only. Open a new terminal, or runsource ~/.cargo/env, before the next step. -
See where the data repository would go (below), what would be imported, and how much history can be replayed. Nothing is written:
memsaga init --dry-runTo keep a project's memory out entirely, for example client work, exclude it now, before step 3: what step 3 commits stays in the history. Add a line to
~/.config/memsaga/config.tomlwith the project's Claude Code directory name, as the dry run lists it. For~/git/clientand every project below it (and any sibling whose name starts withclient-):exclude_projects = ["*-git-client", "*-git-client-*"]. -
Create the data repository, replay the history and import the current state, then register the hooks in each Claude Code config directory.
--skillsalso adds the bundled skills that use cases 3 and 7 use; leave it out if you do not want them. It writes the foldersmemsaga-history,companion-docsandcompanionsunderskills/, replacing any folder of the same name, so rename one first if you already have it:memsaga init memsaga install --skills -
Optional: a private GitHub repository, so the history is backed up and synced between machines. Any name works;
ghneedsgh auth loginonce:gh repo create memories --private --source "$(memsaga repo)" --push -
Check the last sweep, pending changes and push state:
memsaga status
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
~/.config/memsaga/config.toml. 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 its path,
and the commands below use it, so they work wherever yours is.
Claude Code's config somewhere else. memsaga takes Claude Code's config
directories from the account list of CodeV if
you use it (that list includes ~/.claude), and otherwise uses
~/.claude. 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 ~/.config/memsaga/config.toml, 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. memsaga 0.1.1 does not do this; with it, write the lines yourself 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.
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, by
default at most once every ten minutes and at the end of a session (both can
be changed in configuration; memsaga push pushes now); without one, the
history stays on this machine. 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.
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. memsaga
does not scan what it copies for secrets, so keep credentials out of anything
you add to files, dirs or extra_files. 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.
To try it first on example data, install memsaga, 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 a week of history (a bug fix, a memory
tidy-up, companion documents, a file added by hand, a restore), 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.
To look without installing anything, browse
grimmerk/memsaga-example: the
data repository that script builds, with its week of commits on GitHub.
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, and HOME-git-webapp (the
project's memory folder in the repository) as the name memsaga paths shows
for it.
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
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, andclaude --resume <session>, run in theCwd: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.mdgives the commit of each line, and that commit'sSession: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:
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.)
- At session start, a hook asks GitHub whether the repository moved. This takes about half a second and happens at most once a minute per machine. At each prompt the same question runs in the background, and its answer is used from the next prompt on, so a session already open picks the change up a prompt later.
- If it moved, memsaga merges it. A file that changed only in the repository is written to the live file. If both sides changed different lines, the texts are merged. Edits to the same lines are left alone and reported.
- The model gets a short notice with the changed lines, so it does not answer from the copy it loaded earlier.
- Before a Write or Edit, the hook asks GitHub again unless it asked in the last ten seconds, and pulls a change it finds 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. A Read uses the last answer and refreshes it in the background, so an edit made elsewhere within the last minute may reach a read only at the next prompt.
All of this happens inside Claude Code sessions: a turn that changed something
ends with a commit. With an origin remote, the end of a turn also pushes, at
most once per push_min_interval_secs (0 turns these pushes off), and the
end of a session pushes when push_on_session_end is on (the default). 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) ormemsaga 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):
memsaga sync --take live <path>or--take repo <path>, or edit the live file and runmemsaga syncagain. - When setting up another machine: see Setting up another machine.
Details: 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:
- 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 keepMEMORY.mdin step with the files". - 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>'. - Keep what helps. Undo the rest one file at a time with
memsaga restore, or everything withmemsaga restore --all --at <commit before the pass>.--allnever 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 | 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 installregisters memsaga in each config directory'ssettings.json.PostToolUsemarks a turn that wrote a file,Stopcopies and commits at the end of the turn, andSessionEndpushes.SessionStart,UserPromptSubmitandPreToolUsebring 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, at most once a minute.
- 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.
When something looks wrong
memsaga statusshows 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 thatsettings.jsonruns but this machine lacks.- A hook never stops a turn. Its errors go to
<data repository>/.git/memsaga/memsaga.log, and every sweep, push and merge toevents.jsonlnext to it. memsaga diffshows what the next sweep would commit;memsaga sweepcommits now.- An edit from elsewhere that conflicts with yours waits, and
memsaga syncreports it. Pick a side withmemsaga sync --take live <path>or--take repo <path>, or edit the live file and runmemsaga syncagain. - To stop,
memsaga uninstallremoves 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) |
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"]). 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. Names from before this rule are
renamed by the next sweep, as one commit of renames, and older revisions stay
restorable by the new name. Before 2026-09-18 memory was stored at
<label>/projects/<slug>/memory/; the first sweep after upgrading moves it in
one commit, and restore --at still reads older revisions from the old path.
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
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
[[roots]]
path = "~/.claude"
label = "claude"
Without [[roots]], memsaga reads CodeV's ~/.config/codev/accounts.json if
present, else uses ~/.claude. That search does not read
CLAUDE_CONFIG_DIR; init adds the folder it names and writes the roots into
the file (memsaga 0.1.1 does not; list the folder yourself). Without repo,
it uses an existing memsaga
repository called memories in one of the folders the quick start names, else
the place init would choose. If the config file disappears while the
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.
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, and
memsaga sync --take live|repo <path> settles one by picking a side. 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.
The three hooks of use case 10 ask origin at most once a minute per
machine, and before a Write or Edit at most every ten seconds. Only a session
start and a Write or Edit wait for the answer; a prompt or a Read starts the
check in the background and uses the last answer. 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>.
Updating
- Run step 1 of Install by hand again: it
downloads the latest release and replaces
~/.cargo/bin/memsaga. If you built from source, add--forceto thecargo installline. If you installed an archive from the Releases page, replace that binary with the new release's. memsaga install, with--skillsif 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.--skillsoverwrites the bundled skills; if you edited one, the old text is in the history.
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.
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.
-
Remove the hooks from every config directory; Claude Code stops committing:
memsaga uninstall -
Remove the binary, the config file and the install script's receipt:
rm ~/.cargo/bin/memsaga rm -r ~/.config/memsaga -
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 -rIasks once before it removes anything:rm -rI ~/.claude/skills/memsaga-history ~/.claude/skills/companion-docs \ ~/.claude/skills/companions
// faq
What is memsaga?
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”.. It is open-source on GitHub.
Is memsaga free to use?
memsaga is open-source under the MIT license, so it is free to use.
What category does memsaga belong to?
memsaga is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/memsaga)
// retro hit counter
[](https://claudeers.com/memsaga)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA