Memmy架构深度剖析：如何用TypeScript、Electron和SQLite打造Local-First的Agent Runtime

Memmy架构深度剖析：如何用TypeScript、Electron和SQLite打造Local-First的Agent Runtime

【免费下载链接】memmy-agent🍙 A personal AI agent & local memory hub for all AI agents, gives every AI one shared, fully controlled memory and persistent context — all AI remember the same you. Now supports Claude Code, Codex, OpenClaw and Hermes Agent etc.项目地址: https://gitcode.com/gh_mirrors/me/memmy-agent

Memmy 是一个 Local-First 的个人 AI Agent Runtime 与本地记忆中枢（Memory Hub）。它完全用 TypeScript 构建，通过 Electron 提供桌面应用，用 SQLite 作为本地持久化底座，让 Claude Code、Codex、OpenClaw、Hermes 等所有 AI 共享同一份完全由你控制的持久记忆。本文将从 Monorepo 结构、Memory 服务、桌面壳到 Agent Runtime，带你完整剖析这套架构的设计思路。

总体架构：一个本地记忆底座 + 多个入口

Memmy 的核心设计理念是：所有 Agent 和入口（桌面 App、CLI/TUI、外部 Agent 适配器）都共享同一个本地 Memory 服务和 Agent Runtime，数据不离开本机。

整体分为四层：

核心概念速览可见官方文档 docs/cn/concepts/architecture.mdx。

Monorepo 组织：9 个 Workspace 各司其职

项目根目录通过 npm workspaces 组织了整个工程，结构如下（定义在 package.json）：

• Memory/— 记忆服务本体（@memmy/memory），含服务端、CLI、存储、检索、演化算法
• App/backend— 桌面端本地 API 后端，Fastify + SQLite
• App/shell/desktop— Electron 主进程壳
• App/frontend/*— React + Vite 桌面渲染层
• App/memmy-agent— Agent Runtime（模型调用、工具、MCP、渠道接入、TUI）
• AgentSourceCore/、Knowledge/、Migrations/— Agent 来源扫描、知识库、运行时配置迁移

这种分层让每个模块可以独立构建和测试，构建顺序由脚本串联（如memory:build→workspace:build），版本则通过 scripts/sync-project-version.mjs 统一同步。

Memory 服务：SQLite 是 Local-First 的基石

Memmy 的记忆底座是一个绑定127.0.0.1的本地 HTTP 服务，入口在 Memory/src/server/index.ts，默认监听:18960。

存储层有两个亮点：

1. 单一 SQLite 文件搞定全部持久化：基于better-sqlite3，开启 WAL 模式与 5 秒 busy_timeout（见 Memory/src/storage/db.ts），迁移前自动执行VACUUM INTO生成备份，升级零数据丢失。
2. FTS5 全文检索 + sqlite-vec 原生向量检索双通道：在 Memory/src/storage/backend.ts 中声明了fullText: "fts5"与vector: "native"，关键词搜索和语义搜索跑在同一个数据库里，无需额外向量库。
3. 可插拔后端：同一套StorageBackend接口下同时实现了sqlite-local和openmem-cloud-rest两种后端，本地优先，但架构上为云端同步留好了扩展位。

服务启动时还包含用户级锁（acquireUserServiceLock）与 SQLite 文件锁，保证同一时刻只有一个服务实例运行，这对 Local-First 场景的并发安全至关重要。

桌面端：Electron 壳 + React 前端

桌面应用由两部分组成：

• Electron 主进程：App/shell/desktop/package.json 中使用 Electron 38 与 electron-builder 打包，主进程负责拉起 Memory 服务、管理本地 Runtime、处理屏幕采集等系统能力。
• React 渲染层：App/frontend/desktop基于 Vite 构建，页面、状态、i18n 按pages/、state/、i18n/组织，通过api/目录调用本地后端。

后端 App/backend/package.json 则使用 Fastify 暴露本地 API，配合 SQLite 的 app-state-store（含 30 余个 SQL 迁移文件）持久化应用状态，并内置权限管理（permission/permission-manager.ts）保证桌面端所有敏感操作都经过本地授权。

Agent Runtime：Memmy 自己也是 Agent

App/memmy-agent是项目的"大脑"，描述为 "TypeScript refactor of memmy's agent runtime"。它具备完整的 Agent 能力：

• 多模型 Provider：OpenAI、Anthropic、AWS Bedrock、本地模型等，支持 BYOK
• MCP 集成：通过@modelcontextprotocol/sdk接入工具生态
• 多渠道接入：Telegram、Slack、Discord、飞书、钉钉、微信等
• TUI 交互：基于 Ink/React 的终端界面，支持斜杠命令菜单

运行入口 App/memmy-agent/src/main.ts 提供memmy agent、memmy serve（OpenAI 兼容 API，:18990）等命令；Linux 下通过 systemd 用户服务常驻（memmy-memory.service/memmy-gateway.service）。

跨 Agent 记忆：架构的最终形态

Memmy 最有价值的架构产出是"跨 Agent 任务连续性"——用 AgentSourceCore/ 中的读取适配器解析 Codex、Claude Code、Cursor 等各 Agent 的本地会话文件，把散落在各处的历史统一汇入同一份 SQLite 记忆库，实现"所有 AI 记住同一个你"。

数据始终留在本地：

关键源码路径速查

总结

Memmy 的架构可以概括为三点：

1. TypeScript 全栈统一：从 Memory 服务、Fastify 后端到 Electron 主进程与 React 前端，同一语言贯穿所有层，类型契约（local-api-contracts）跨层共享；
2. SQLite 即数据库、向量库、全文索引：better-sqlite3 + FTS5 + sqlite-vec 让 Local-First 不需要任何额外基础设施；
3. Electron 只负责体验，Memory 才是核心：Memory 服务可脱离桌面端独立运行（memmy-memoryCLI + systemd 服务），Agent、脚本、CLI 都能接入同一份本地记忆。

这就是一个 Local-First Agent Runtime 的完整答案：把"记忆"做成独立、可移植、本地可控的基础设施，让所有 AI 工具围绕它协作。

【免费下载链接】memmy-agent🍙 A personal AI agent & local memory hub for all AI agents, gives every AI one shared, fully controlled memory and persistent context — all AI remember the same you. Now supports Claude Code, Codex, OpenClaw and Hermes Agent etc.项目地址: https://gitcode.com/gh_mirrors/me/memmy-agent