MemoSync

Co-manage your coding agent's memory: see what it remembers, decide what it keeps, choose what it uses, and audit how it used it.

_{MemoSync in the middle of a turn. (A) the pre-turn review of long-term memory, (B) the Memory Board, (C) the working memory confirmed for this turn, (D) inline memory citations with a Stop control, (E) the post-turn Memory Use Audit, (F) the per-turn Memory Record.}

Demo video

https://github.com/user-attachments/assets/488a1e41-5a01-4c01-ac76-5c37b8e764f0

Why MemoSync

Coding agents accumulate memory — CLAUDE.md files, auto-extracted notes, session summaries — but the developer rarely knows what is in it, what the agent brought into a turn, or whether the agent followed it. Memory changes behind your back, stale rules from an old project leak into a new one, and a violated constraint only shows up when the tests fail.

MemoSync is a local web workbench for coding agents that treats agent memory as a shared, operable representation: a store of versioned memory items that you and the agent both read, propose changes to, and act on. At every stage of a turn the system shows what changed and proposes an action; you review and decide. Nothing is written to memory, injected into a turn, or enforced on the agent without your say-so.

_{The design borrows the metamemory loop from cognitive psychology: meta-level judgements monitor object-level memory processes and control them. With a coding agent, that loop is split across the human–agent boundary — the agent runs the memory processes, but the developer needs to keep the monitoring and control. MemoSync closes the loop at five points: how memory is represented, how it evolves, what is selected for a turn, how it is applied during execution, and what effect it had.}

Each memory item is a one-line summary with a scope (personal, project, or session) plus metadata that accumulates over time: a detailed form the agent loads on demand, a version number, a status, a usage count, and a history log. The same item takes a different form at each stage of a turn — a proposal card, a working-memory row, an inline citation, an audit verdict — and two persistent views, the Memory Board and the Memory Record, carry it between turns.

Contents

• How a turn works
  • 1 · Evolution — review changes to long-term memory
  • 2 · Selection — compose the working memory
  • 3 · Execution — trace and interrupt memory use
  • 4 · Impact — audit memory use and enforce a rule
  • Between turns — Memory Board and Memory Record
• Features at a glance
• Quickstart
• Configuration
• Command line
• How it is built
• Development
• Data, privacy, and usage logging
• Acknowledgements
• License

How a turn works

The walkthrough below follows a developer adding Stripe checkout to a small shop whose store already holds personal habits (M-02 "Use pnpm, never npm"), project facts (M-07 "Prices are stored as integer cents, never floats"), and lessons from an earlier payments project.

1 · Evolution — review changes to long-term memory

Before a turn starts, MemoSync presents three review steps for proposed changes to long-term memory. Each change needs explicit approval before it is written to the store.

1. Review New Memory Candidates — items extracted from the last exchange (including the real work trajectory: files touched, commands run, errors hit), each with a proposed scope. Accept, edit, rescope, or dismiss.
2. Memory Transfer Suggestions — rules from other projects that may apply here. Copying a rule verbatim drags in source-project details, so transfer is two-staged: an encoder abstracts the source rule into a project-independent form, a decoder rewrites it against this project's memory and the current task. Source, abstract rule, and rewritten rule sit side by side so every transformation is reviewable.
3. Review Suggested Changes to Existing Memories — conflicts between new and old items, redundant pairs to merge, and items that have gone stale, each with a one-line reason. Repeatedly violated items surface here with a revision proposal.

2 · Selection — compose the working memory

Working Memory for This Turn opens before the agent starts. Each proposed row shows the item, its scope, and a line stating how the agent is expected to use it ("Compute the checkout total from stored prices, not the client payload"). Remove a row, add items from the memory pool, or adjust the selection in plain language — "Anything about the API server setup? Drop the commit-style ones" — and the in-card assistant answers with live M-NN chips. What you confirm is exactly what the agent is charged against later.

3 · Execution — trace and interrupt memory use

As the reply streams, the agent is instructed to cite each memory it applies. Hover a citation for the item's content, scope, version, and usage count. Every citation includes a Stop control: press it when the agent does the opposite of what the item says, and execution is interrupted. A recovery card quotes the sentence and asks what should have happened; write the correction, optionally tick Enforce for this resumed run, and the agent continues in the same main session. Use the item's Save control to retain corrected memory content.

4 · Impact — audit memory use and enforce a rule

When a turn ends, the Memory Use Audit reports one of four verdicts for each injected item: violated, shaped the turn, not applicable, or no visible effect. To avoid relying on the agent's self-report, a separate judgment of the full exchange runs after the turn, so an item violated without being cited is still caught — verdicts are tagged audit-found or self-reported. A violated row offers Where used (scroll to the judged sentence and the tool call behind it) and Enforce this next run (the item becomes a mandatory row in the next turn's working memory that only you can remove). Verdicts are written into each item's history.

Between turns — Memory Board and Memory Record

The Memory Board shows every item as one column per scope. Drag an item between columns to rescope it (dropping into another project runs the same encoder/decoder preview as a transfer); open an item to edit its content and detailed form, change its scope, transfer or archive it, and read its full history; archived items can be restored. The Memory files card keeps a Markdown copy of the board in sync, so the accumulated memory stays usable with CLAUDE.md-style files and other agents, and can import an existing configuration file as candidates for review.

The Memory Record in the sidebar lists, for each turn of a session, what was proposed, selected, cited, interrupted, and audited. It persists independently of the agent's context window, so after the conversation is compacted both you and the agent can still refer to it.

Features at a glance

• Versioned memory items — one line each, optional detail loaded on demand, scoped to personal / project / session, with status, usage count, and full history with revert.
• Mixed-initiative review at every stage — the system proposes, you decide: candidates, transfers, conflicts/redundancy/staleness, per-turn selection, audit follow-ups.
• Cross-project transfer with an encoder/decoder pair that abstracts and re-localizes rules instead of copying them.
• Inline citations with per-citation Stop, correction-and-resume, and one-run enforcement.
• Independent post-turn audit with four verdicts and source tags (audit-found / self-reported).
• Memory Board + Memory files — drag-to-rescope, search, archive/restore, Markdown projection that syncs both ways, import of existing config files.
• Memory Record — a per-turn ledger that survives context compaction.
• Stable session injection — confirmed memory rides the session as a snapshot plus per-turn deltas, so memory edits can take effect without restarting the conversation.
• Claude Code, Codex, and Pi engines — official CLI subscriptions, isolated GLM testing, or an in-process Pi agent on any OpenAI-compatible endpoint via the Model Registry; memory reasoning forks from the chosen engine's conversation. Claude Code also offers DeepSeek and per-chat vendor selection.
• A full coding workbench underneath — project-first sidebar, plan mode, rich transcript rendering, embedded terminal, file and git panels, session resumption, local-first persistence.

Quickstart

Requirements: Bun 1.3.5 or newer and a configured provider. MemoSync bundles the Claude Agent SDK runtime; the Codex engine also requires a current codex CLI on PATH. You can use your official CLI subscriptions, or test both engines with GLM in a separate profile. The Pi engine runs in-process (no CLI to install): give it any OpenAI-compatible endpoint through the Model Registry in Settings → Providers, or export OPENROUTER_API_KEY. Its model picker takes any registry model id, not just the catalog suggestions.

git clone <this repository> MemoSync
cd MemoSync
bun install
cp .env.example .env      # then set GLM_API_KEY for isolated testing
bun run build
bun run start

MemoSync opens at localhost:3210. For GLM, choose Claude Code → GLM, or Codex (the isolated configuration supplies its GLM model). Add a project folder and send a message to prepare the first memory review.

If Bun is not installed:

curl -fsSL https://bun.sh/install | bash

A step-by-step guide in Chinese, written so that an AI coding assistant can execute it end to end, is in docs/DEPLOY.zh-CN.md.

Configuration

All configuration is read from .env in the project directory (see .env.example).

With DEEPSEEK_API_KEY set, MemoSync derives the whole ANTHROPIC_* bundle itself and ignores leftover ANTHROPIC_* / CLAUDE_CODE_* exports from other Claude Code setups in your shell, so a stray ANTHROPIC_BASE_URL cannot hijack the engine.

The composer exposes an engine picker and, for Claude Code, a vendor picker (DeepSeek, GLM, Anthropic). For official Claude subscriptions choose an Anthropic model; the sonnet and opus aliases resolve in the installed Claude runtime. Leave MEMOSYNC_ISOLATE_CLI and MEMOSYNC_CLI_PROFILE_DIR unset when using existing official subscriptions. Study deployments retain their single configured Claude model.

Isolated mode gives child processes separate CLAUDE_CONFIG_DIR and CODEX_HOME directories without changing the server's HOME, shell settings, ~/.claude, or ~/.codex. It strips inherited OAuth and provider routing variables. Codex receives a provider definition through process arguments and a key through an environment variable, with an ephemeral credential store; no credential is written to a Codex config or auth file. Missing explicit credentials fail rather than use your normal login. Claude memory branches and title helpers use the same isolation rules.

For a live check of both engines, export GLM_API_KEY in the current shell and run:

bun run scripts/smoke-isolated-branches.ts

The check creates a temporary workspace and profile, exercises three parallel forks, review continuation, working-memory selection, main-context isolation, and post-turn audit, then removes its temporary files. Add claude or codex to test one engine. Provider calls use the configured GLM account.

bun run scripts/smoke-memosync-pipeline.ts claude exercises the complete application coordinator with the real memory prompts and parsers across two turns, automatically reviewing the test proposals. Use codex for the other engine. Both checks isolate all CLI state in a temporary profile; the full pipeline check has a ten-minute limit.

The GLM endpoints and Claude [1m] selector follow the GLM model guide. CLI profile behavior is documented in the Claude environment reference and Codex configuration reference.

Command line

bun run start                  # localhost:3210, opens the browser
bun run start --port 4000      # custom port
bun run start --no-open        # do not open the browser
bun run start --remote         # bind 0.0.0.0 for LAN / Tailscale access
bun run start --password <s>   # require a password before the app loads
bun run start --share          # temporary public trycloudflare.com URL + QR code
bun run export-data [--full]   # bundle local data into a tar.gz (see below)

How it is built

• Stack. React 19 + TypeScript on the client, Bun on the server. Memory items and their histories live in SQLite; projects, chats, and transcripts are append-only JSONL logs with snapshot compaction.
• Agent runtime. Claude Code runs through the Claude Agent SDK query() interface with an asynchronous prompt queue. Codex runs through the Codex app-server protocol with native thread creation, resume, fork, dynamic tools, and per-turn developer instructions. Pi runs in-process through the pi-coding-agent SDK against the Model Registry connection, with per-chat session files under the MemoSync data root, resume/fork through the session file, and the memory block prepended to the prompt (Pi has no developer-instructions channel). Its bash tool spawns with a scrubbed environment (credential-looking variables are removed), though — like the other engines — it shares the server's user account, so a model can still read files the server can. All three support official authentication or the isolated provider profile described above.
• Pi model capabilities. Before the first message, the picker reads the configured registry's /models list and looks up the selected ID, including manually entered models. Live metadata takes priority; models.dev fills missing capabilities for the actual endpoint, followed by Pi's bundled metadata for official OpenAI/OpenRouter endpoints. A custom relay can also obtain reasoning levels by an unambiguous model ID/canonical ID match, preferring the model maker's record; another endpoint's prices, context and output capabilities are not borrowed this way. Both the picker and request transport use this resolver, including OpenRouter's mandatory reasoning, defaults and max, and gateways' supported_reasoning_levels. Each field is merged separately: live context, prices (including zero), input modalities and explicit structured-output support stay intact when reasoning levels are missing. Unknown capabilities use Provider default; a thinking switch, token budget or explicit empty level list does not invent effort levels. Pi turns read the last cached snapshot synchronously and refresh metadata in the background; a cold cache leaves reasoning and unknown output limits unspecified instead of delaying a message for a catalog timeout. Provider responses are cached per endpoint and credential for five minutes; the public models.dev catalog is cached on disk for 24 hours, fetched without provider credentials, and retains its last good data offline. No additional LiteLLM service is required. This resolver serves the Pi Model Registry path; Claude Code and Codex retain their own CLI/SDK integrations.
• Memory tools. The agent sees the memory store through an MCP server: load_memory_detail fetches an item's detailed form on demand and propose_memory lets the agent nominate a candidate mid-turn (it still goes through your review).
• Parallel memory branches. Candidate extraction (C), transfer (T), and memory changes (M) start together. Candidate decisions continue T and M in their existing conversations; transfer decisions continue M. A further branch selects working memory and writes expected uses after approved changes reach the store. An audit branch judges the completed turn, including uncited tool evidence. MemoSync has no direct-API fallback: every memory model call uses the chosen CLI runtime. Before the first main turn is persisted, branches explicitly start with empty history because Claude cannot fork an unpersisted session. Implementation and validation details.
• Confirmed memory injection. Only confirmed items enter the main Memory Block and detail-tool allowlist. Claude keeps its session and updates selections through deltas; Codex receives the selected block and expected uses through per-turn developer instructions. Branch analysis transcripts stay out of the main conversation. Provider cache reuse depends on the runtime and provider; no latency saving is assumed.
• Local-first. Everything is stored under ~/.memosync/data/; there is no server component beyond the local Bun process.

src/
├── client/                React UI
│   ├── app/               Router, pages (chat, Memory Board, settings), central state
│   ├── components/        Transcript messages, memory cards and gates, chat chrome
│   └── stores/            Zustand stores
├── server/                Bun backend
│   ├── agent.ts           Turn coordination: review gates, injection, interrupt/resume, post-turn passes
│   ├── deepseek-engine-env.ts   Derives the engine's ANTHROPIC_* bundle from DEEPSEEK_API_KEY
│   ├── chat-providers.ts  Per-chat vendor routing (DeepSeek / GLM)
│   ├── memory/            The memory engine
│   │   ├── MemoryStore.ts     Versioned items, events, relations (SQLite)
│   │   ├── capture.ts         Candidate extraction and routing
│   │   ├── checkup.ts         Conflict / redundancy / staleness / promotion checks
│   │   ├── relevance.ts       Per-turn suggestion and expected-use planning
│   │   ├── trace.ts           Post-turn memory-use audit
│   │   ├── transfer.ts        Cross-project transfer (encoder / decoder)
│   │   ├── injection.ts       Snapshot + delta injection planning
│   │   ├── fork-query.ts      Out-of-band questions on a fork of the session
│   │   └── tools.ts           MCP tools exposed to the agent
│   ├── event-store.ts     JSONL persistence, replay, and compaction
│   └── ws-router.ts       WebSocket routing and subscriptions
└── shared/                Types, protocol, tool hydration

Development

bun run dev          # client (5174) + server (5175) with hot reload
bun test src/        # unit + integration suite (LLM passes are stub-injected; no network)
bun run check        # typecheck + both client builds

End-to-end scripts under scripts/ (e2e-claude-memory.ts, e2e-full-app.ts, e2e-memory-matrix.ts, ui-flows-check.ts) drive a live instance with real model calls and are not part of bun test.

Data, privacy, and usage logging

Everything MemoSync produces stays on your machine under ~/.memosync/data/: the memory store (memory.sqlite), its Markdown projection (memories/), the chat and project logs, and a local usage log (experiments/events.jsonl) that records how the memory features are used — reviews, injections, citations, interrupts, audits, panel visibility — stamped with a random per-install id. Nothing is uploaded automatically.

bun run export-data          # usage log + memory library
bun run export-data --full   # additionally chat/session logs and transcripts

The default bundle deliberately excludes chat transcripts and project logs; --full is opt-in. See docs/DATA_AND_TELEMETRY.md for the exact file layout and event families.

Acknowledgements

MemoSync builds on Kanna, an open-source agent workbench, and on the Claude Agent SDK. The default models are served by DeepSeek; GLM models by Zhipu AI.

License

MIT