Memory Ferry

Memory Ferry · 记忆摆渡 is a local-first, cross-device long-term memory and reusable-Skill layer for AI agents. Put an ordinary Vault folder in iCloud Drive, OneDrive, Dropbox, Syncthing, or a mounted NAS, then connect Codex, Claude Code, Cursor, OpenCode, DeepSeek Harness, Gemini CLI, GitHub Copilot CLI, and MiniMax Code to the same memory.

中文说明 · English user guide · 中文使用手册

Version 0.7.0-beta.1 does not provide end-to-end encryption. Never store passwords, API keys, tokens, private keys, recovery codes, or other secrets.

Why it exists

• Cross-computer: sync ordinary files without a hosted control plane or database daemon.

• Cross-agent: expose one MCP and CLI contract instead of locking memory to a model vendor.

• Offline-friendly: each write is an independent immutable JSON event that syncs later.

• Conflict-tolerant: concurrent additions never overwrite one another; updates converge deterministically.

• Reusable Skills: validate one portable source, render optional Agent overlays, and distribute target-specific packages by content hash on macOS and Windows.

• Low cost: reuse storage and sync software you already operate.

Related MCP server: SharedBrain

Supported agents

Quick start

Requires Node.js 20 or newer:

npm install -g memory-ferry@beta

memory-ferry init "/path/to/your/synced/MemoryFerryVault"
memory-ferry agents install all
memory-ferry remember "Prefer concise answers" --kind preference --scope global
memory-ferry recall "answer style"
memory-ferry ui

During the beta period, use the explicit @beta tag. Upgrade or uninstall with:

npm install -g memory-ferry@beta
npm uninstall -g memory-ferry

The dashboard is loopback-only, opens in your browser, supports English and Chinese, manages multiple Vaults, connects or disconnects agents, reports Skill compatibility, migrates Vault contents safely, and reconciles Skills every five minutes while running.

Portable and Agent-adapted Skills

Every Skill starts with one portable source at <Vault>/skills/<skill-name>/SKILL.md. Memory Ferry validates the open Agent Skills frontmatter before distribution. Run:

memory-ferry skills inspect
memory-ferry skills sync all

For product-specific behavior, add an optional memory-ferry.yaml manifest and small adapters/<agent>/ overlays. An overlay can merge frontmatter.yaml, append APPEND.md, and provide extra files such as Codex agents/openai.yaml; it may not replace the common SKILL.md. Memory Ferry renders and hashes each destination separately, groups Agents that share a discovery directory, blocks conflicting overlays, rejects non-portable symlinks, and preserves unrelated user-owned Skills. See the Skill compatibility guide.

Windows portable app

The Windows x64 release is a portable MemoryFerry.exe: no installer and no separate Node.js installation are required. Put the EXE in a permanent folder and double-click it. It starts without a console window and opens the local dashboard. Use the bundled MemoryFerry-CLI.cmd when you need command-line output.

The beta is not commercially code-signed, so Windows may show an unknown-publisher warning. Verify the included SHA-256 file and keep SmartScreen enabled.

Storage model

MemoryFerryVault/
├── memory-ferry.json
├── memory/events/<device-id>/<date>/<event-id>.json
└── skills/<skill-name>/...

Device identity, clocks, event caches, and optional Ollama embedding indexes stay outside the synchronized folder. The Vault contains no live SQLite database, WAL, or lock file.

Upgrade compatibility

Memory Ferry recognizes existing Agent Vault Sync installations:

• agent-vault.json is accepted and a new memory-ferry.json companion manifest is created without deleting the old file.

• ~/.agent-vault-sync state is migrated to ~/.memory-ferry when the new state does not exist.

• AGENT_VAULT_* environment variables remain fallbacks for their MEMORY_FERRY_* replacements.

• Reconnecting an agent removes the old managed agent-vault entry and writes memory-ferry.

• The legacy agent-vault CLI alias remains available during the beta migration period.

Back up important Vaults before upgrading and allow your sync client to finish before opening the same Vault on another computer.

Optional semantic recall

If local Ollama is available, recall and context blend semantic similarity with Unicode/CJK text scoring. Set MEMORY_FERRY_EMBED=off or pass --no-semantic to use text-only search. Embedding indexes remain local and are repaired before the first query returns after cloud sync or migration.

Development

npm ci
npm run test:all
npm audit --omit=dev
npm pack --dry-run

Windows releases are built and smoke-tested in GitHub Actions. See CONTRIBUTING.md, SECURITY.md, and architecture.md.

License

MIT. Standalone releases also include Node.js and third-party license notices.