https://github.com/user-attachments/assets/488a1e41-5a01-4c01-ac76-5c37b8e764f0
Coding agents keep memory: CLAUDE.md files, notes they extract, lessons from earlier sessions. You rarely see what is in it, what the agent took into this task, or whether it followed it. MemoSync is a local workbench for Claude Code, Codex and Pi that puts that memory on screen.
- Every change to memory waits for your review.
- Before each turn, you confirm what goes in.
- While the agent works, its replies cite the memories they use.
- After the turn, a separate check reports what was followed and what was ignored.
When a turn doesn't need that much attention, switch to Automatic and the agent handles memory on its own.
A turn with memory
Memory is a set of short items. Each has a scope (personal, project or session), a version and a history. The same item shows up in four places during a turn.
1. Review what the agent learned
Before a turn starts, MemoSync shows the memory changes it proposes, in three groups. Accept, edit, rescope or dismiss each one. Nothing reaches the store until you do.
- New candidates: taken from your last exchange and from what the agent actually did (files, commands, errors).
- Transfers from other projects: a rule from another project is first rewritten in general terms, then adapted to this project. You see all three versions side by side.
- Fixes to existing items: conflicts, duplicates to merge, and rules that have gone stale or keep being broken.
2. Choose the working memory
Working Memory for This Turn lists the items the agent intends to use, each with one line saying how. Remove rows or add others from your library. You can also ask in plain words, for example "drop the commit-style ones". The agent starts only after you confirm, and the audit later checks it against exactly this list.
3. Follow it while it works
Replies cite the memories they apply (M-07). Hover a citation to see the item.
If the agent is doing the opposite of a memory:
- Press Stop on that citation.
- Write what should have happened.
- Optionally enforce the item for the rest of the run.
The agent resumes from the sentence where you stopped it, and your correction is saved to the item.
Citations are what the agent says it used, not proof that it did. That is why step 4 exists.
4. Check the result
When the turn ends, a separate pass reads the whole exchange and rates every selected item: violated, shaped the turn, not applicable, or no visible effect. Each verdict says whether the audit found it or the agent reported it, so a violation the agent never cited still shows up.
For a violated item:
- Where used jumps to the sentence and tool call behind the verdict.
- Enforce this next run makes the item a required row in the next turn. Only you can remove it.
The audit is a model judgment and can be wrong.
Between turns
The Memory Board is the whole library, one column per scope.
- Drag an item to change its scope.
- Open an item to edit it, read its history, or archive it.
- Memory files keeps a Markdown copy for other tools, and imports an existing
CLAUDE.md as candidates for review.
The Memory Record, on the right of every chat, logs each turn: what was proposed, selected, cited, stopped and audited. It survives context compaction, so you and the agent can still refer back to it.
Automatic
Reviewing every turn pays off when memory matters, and is too much for a quick question. Set Settings → Memory → Control to Automatic:
- No cards before the turn. The agent reads the memory index and loads the items it needs.
- After the turn it learns in the background. Safe changes apply on their own, each with Revert; sensitive ones wait on the Memory Board, which shows a count in the sidebar.
- The audit still runs, but speaks up in the chat only when a memory was violated. Every verdict stays in the Memory Record.
Quick start
You need Bun 1.3.5 or newer, plus one of:
- Claude Code or Codex already signed in, or
- an API key from any provider.
git clone https://github.com/SLEEPYBQ/MemoSync.git
cd MemoSync
bun install
bun run build
bun run start
MemoSync opens at http://localhost:3210. Then:
- Open Settings → Models, pick an engine and give it access (see the next section).
- Click + in the sidebar, then Add project to open a folder.
- Send a task. Your library starts empty, so the first turns are mostly proposals. Review them, and the memory builds up as you work.
Connect a model
An engine is the agent that does the work. Access is how it reaches a model. Both are set in Settings → Models.
| Engine | What it runs | Access |
|---|
| Claude Code | Your installed claude, or the copy bundled with the Agent SDK | Your sign-in, or an API connection that speaks the Anthropic API or OpenAI Chat |
| Codex | Your installed codex (required) | Your sign-in, or an API connection that speaks the OpenAI Responses API or OpenAI Chat |
| Pi | Built into MemoSync | An API connection that speaks OpenAI Chat or Responses |
When a connection speaks only OpenAI Chat, MemoSync translates for Claude Code and Codex through a local gateway on 127.0.0.1; the engine card says via translation. The engine never sees your key.
Your sign-in. The engine uses the login and settings you already have, and MemoSync adds nothing to them. If the engine shows Not signed in, sign in from your terminal, then press Detect again.
API connection.
- Click Add connection.
- Either pick a provider or choose Custom endpoint:
- A provider from the built-in list: more than seventy vendors, relays and local servers, with endpoints filled in and, for most, their models. Paste your key, and add a model ID if the list is empty.
- Custom endpoint: enter a base URL, its protocol, a key and model IDs.
- Press Test to send one small request and confirm the endpoint answers.
- Back on the engine, choose the connection and a default model.
Engines on an API connection run in a separate profile under ~/.memosync/data/cli-profiles, so your own ~/.claude and ~/.codex are never read or changed. Keys are stored in ~/.memosync/data/credentials.json, readable only by you, and are never sent back to the browser.
MemoSync finds claude and codex on your PATH and in the usual install folders. To point an engine at a specific executable, set its path on the engine's card.
Everyday controls
In the composer, under the message box:
- the project;
- memory on or off for this chat;
- the engine and the model;
- reasoning effort;
- Plan Mode, where the agent proposes a plan and waits for you before it acts.
In Settings → Memory:
| Setting | What it does |
|---|
| Use Memory | Turn memory off everywhere. Your library stays on the Memory Board. |
| Learn From Chats | Keep using memory, but stop proposing new items. |
| Control | Review each turn runs the four steps above. Automatic works without asking; see Automatic. |
| Memory Changes | Ask First holds every proposal for review. Apply Automatically applies non-sensitive ones right away, each with a one-click Revert. Sensitive proposals always ask. |
| Memory Preview | Show the working memory card before each turn, or skip it when nothing applies. |
Memory Changes and Memory Preview apply under Review each turn.
Elsewhere in Settings:
- Appearance: language (English or 简体中文) and theme.
- Notifications: sounds and system notifications when a chat needs you.
- Keybindings: all shortcuts.
- Skills: globally installed agent skills.
Run it elsewhere
bun run start --port 4000 # another port
bun run start --no-open # don't open a browser
bun run start --remote # listen on 0.0.0.0 (LAN, Tailscale)
bun run start --password <pw> # ask for a password before the app loads
bun run start --share # temporary public URL with a QR code
bun run start --help lists every option.
Data and privacy
Everything MemoSync stores lives under ~/.memosync/data/ on your machine:
- memories (SQLite, plus the Markdown copy);
- chats and settings;
- API connections;
- a local usage log of how the memory features are used.
Nothing is uploaded by MemoSync. Your model provider does receive the conversation, the selected memories and the project context the agent reads.
The agent and its terminals run as your user, with access to your files. Profile isolation separates configuration, not the filesystem.
To stop the usage log, set MEMOSYNC_USAGE_LOG=0. To bundle your data into an archive:
bun run export-data # usage log, memories and settings
bun run export-data --full # also chat transcripts
Exports never include API connections or keys.
docs/DATA_AND_TELEMETRY.md describes each file and event.
Development
bun run dev # client :5174 + server :5175, hot reload
bun test src/ # unit and integration tests, no network
bun run check # typecheck + client builds
The server code is in src/server/:
agent.ts coordinates a turn;memory/ holds the memory engine: capture, checkup, selection, audit and transfer;model-access/ resolves engines and connections.
The client is a React app in src/client/. Development data goes to ~/.memosync-dev/.
Acknowledgements
MemoSync started as a fork of Kanna. It runs:
Provider presets and engine discovery are adapted from Magpie. Provider marks come from Lobe Icons. Licenses are in THIRD_PARTY_NOTICES.md.
License
MIT
