拓冰网站定制 
Magic Context存储层深度剖析SQLite Schema、稳定项目身份与迁移机制全解【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-contextMagic Context是 CortexKit 生态中为编码 Agent 打造的海马体主打无界上下文、自管理记忆、一个会话用一生。它的存储层全部建立在SQLite之上一台机器共享同一个context.db记忆按稳定项目身份归档升级时通过版本栅栏Schema Fence 迁移机制安全演进。本文带你完整看懂 Magic Context 的 SQLite 表结构、项目身份算法与迁移/备份机制无需源码基础也能读懂。一、存储布局一个数据库管住全部状态Magic Context 的所有状态集中在两个 SQLite 文件里位于同一目录文件归属职责context.dbTypeScript 插件所有宿主共享记忆、笔记、区室compartment、工作区等store.dbRust 模块mc-store每会话的缓存状态、区室历史、审计痕迹默认路径~/.local/share/cortexkit/magic-context/context.db可用环境变量MAGIC_CONTEXT_STORAGE_DIR覆盖后端自动选择Bun 下走bun:sqliteNode/Electron 下走node:sqlite行为一致每个连接先设 5 秒busy_timeout打开已就绪的库不拿写锁因此多个 Agent 宿主OpenCode、Pi、OMP可以同时启动而互不排队。 两个库是一个一致性单元任何一侧的权威与镜像状态都引用对方备份/回滚时必须成对操作。完整说明见官方文档 storage.md。二、Schema 与版本栅栏为什么升级不炸库这是 Magic Context 存储层最硬核的设计核心只有一句话版本必须锁步lockstep对不上就拒绝打开数据库。关键规则LATEST_SUPPORTED_VERSION是唯一事实来源定义在 storage-db.ts当前值为94它必须与 migrations.ts 中最新版本号相等锁步测试schema-version-fence.test.ts强制两者同步移动Fail-closed失败即关闭如果构建能理解的版本低于库里实际版本进程拒绝打开库并进入保护状态——每次主变换直接抛出可恢复错误而不是让提示词失控增长或悄悄回退到原生压缩迁移时机守卫若仍有运行旧版本插件的宿主进程占着库迁移会被拒绝并记录日志避免新库 旧进程的组合版本车道version lanes10000的版本号保留给上游 Magic Context≥10000预留给共享context.db的分支插件两条互不干扰规则见 migration-version-lanes.md。加一个新迁移的 5 步标准动作在 migrations.ts 追加下一版本并配一份migrations-vN.test.ts把LATEST_SUPPORTED_VERSION抬到同一数字忘了这步 迁移后数据库拒绝打开同步更新storage-db.ts里的全新安装 schema让新库直接落到最终形态无需重放全部迁移用 storage-schema-helpers.ts 中的ensureColumn/healAllNullColumns兜底老库即使丢了迁移记录也能补齐列、回填默认值若表按会话隔离登记进SESSION_SCOPED_TABLES否则删除会话时该行会永久泄漏。三、核心表速览谁管记忆谁管会话Rust 侧的store.db迁移链定义在 lib.rs从中可以摘出几张最有代表性的表表名作用一句话mc_cache_state每会话的持久缓存状态带row_version乐观并发控制mc_compartments区室历史会话被切成记忆单元含多档复述层 p1–p4 与重要度衰减率mc_memories项目记忆主表UNIQUE(project_path, category, normalized_hash)去重被替换的记忆用superseded_by_memory_id记录mc_memory_mutation_log只追加的变更日志归档/删除/更新不重渲基线而是以小 delta 补丁下发保护提示词缓存mc_user_memories跨项目的用户画像记忆user-profile基线来源mc_workspaces/mc_workspace_members跨项目工作区成员项目可共享指定分类的记忆mc_pass_trace/mc_chunk_transcripts每次变换的接收/完成/拒绝审计痕迹可恢复的压缩转录表分两类会话级带harness列区分宿主如pi/opencode与项目级刻意跨宿主共享——从 Pi 写入的记忆同一项目下 OpenCode 也能读到。删除会话与孤儿清扫都依赖 storage-session-tables.ts 里的完整清单。四、稳定项目身份记忆为何不会丢记忆按什么键归档直接存路径是最朴素的答案也是最大的坑——移动目录、符号链接、大小写差异都会让记忆失联。Magic Context 的答案在 project_identity.rs一个目录在context.db中用一个身份而不是路径来标识有 git 历史的检出是git:根提交哈希否则是dir:路径 MD5 前 12 位。这套算法的巧妙之处git:身份永不变化取git rev-list --max-parents0 HEAD的根提交哈希多条无关历史取字典序最小目录怎么挪、换什么名字记忆池始终跟得上且结果永久缓存dir:身份每 5 分钟复检因为目录后来可能git init成仓库需要升级为git:身份故障时的降级策略git 临时不可用超时、二进制缺失时复用该目录或其同仓库祖先最后一次成功的git:身份绝不落到dir:——否则会为同一个检出生成别人不会计算的新身份记忆被拆成两个池子宿主侧记忆文件宿主每次 git 探测成功后把身份写到context.db旁边的project-identities/边车文件中Rust 模块直接复用保证两条代码路径算出完全相同的值家目录不算项目allowHomeProject关闭时直接拒绝避免把生活记进记忆库。 一句话总结身份稳定记忆才稳定——这是Memory that manages itself的底层前提。五、迁移机制从双库到单库的一次性大手术context.db与store.db曾经并行存两份项目记忆靠镜像机制保持同步。如今这套镜像已退役迁移 61定义于 single_store_schema.rs把所有领域表搬进context.db并删除旧表。迁移引擎实现于 single_store_migrate.rs流程堪称教科书级先备份两个文件都快照到备份目录并在任何写入前打印目录位置切到 rollback-journal 模式SQLite 只有在非 WAL 模式下才能对 ATTACH 的多个库做跨文件原子提交这步保证拷贝、标记、缓存重置要么全成要么全败一个BEGIN IMMEDIATE横跨两文件建表 → 逐项目分类拷贝 → 重置模块缓存 → 清除镜像/权威表 →验证包括从两边分别渲染 m0 基线且必须逐字节一致的渲染检查→ 才删旧表、写入共享的迁移印章任何拒绝或错误都回滚两个文件还支持--dry-run走完全流程后原样回退。用户侧只需要一条命令退出所有宿主后magic-context doctor single-store migrate如果两个库对是否已迁移说法不一模块会以稳定的错误令牌single_store_state_split拒绝服务并给出明确指引而不是带着脏数据继续跑。六、备份与修复日常运维清单备份backup-live-stores.sh 用VACUUM INTO快照context.db和store.db——单事务内读取、不拿写锁会话正在写入也能得到一致副本每份快照附带完整性校验与 schema 版本恢复时可精确匹配构建的栅栏版本恢复停掉所有占用进程 → 删除-wal/-shm文件 → 用快照覆盖两个库都要→ 只启动一个宿主修复npx cortexkit/magic-context doctor repair-db修复损坏的context.db动手前先把坏文件打包成.corrupt-backup-时间戳。七、小结三层防线撑起一生的会话层机制解决的问题版本层栅栏 锁步 失败即关闭新库旧构建互不踩坑身份层git:/dir:稳定项目身份记忆跨目录、跨宿主管线复用迁移层跨文件单事务 渲染级验证 全量备份双库合一无数据丢失想继续深入推荐按这个顺序阅读storage.md存储总览→ rust-module.mdRust 模块与回滚→ migrations.ts迁移全景。看懂这套存储层你就理解了 Magic Context 为何敢承诺一个会话用一生。【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-context创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Magic Context存储层深度剖析：SQLite Schema、稳定项目身份与迁移机制全解
Magic Context存储层深度剖析SQLite Schema、稳定项目身份与迁移机制全解【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-contextMagic Context是 CortexKit 生态中为编码 Agent 打造的海马体主打无界上下文、自管理记忆、一个会话用一生。它的存储层全部建立在SQLite之上一台机器共享同一个context.db记忆按稳定项目身份归档升级时通过版本栅栏Schema Fence 迁移机制安全演进。本文带你完整看懂 Magic Context 的 SQLite 表结构、项目身份算法与迁移/备份机制无需源码基础也能读懂。一、存储布局一个数据库管住全部状态Magic Context 的所有状态集中在两个 SQLite 文件里位于同一目录文件归属职责context.dbTypeScript 插件所有宿主共享记忆、笔记、区室compartment、工作区等store.dbRust 模块mc-store每会话的缓存状态、区室历史、审计痕迹默认路径~/.local/share/cortexkit/magic-context/context.db可用环境变量MAGIC_CONTEXT_STORAGE_DIR覆盖后端自动选择Bun 下走bun:sqliteNode/Electron 下走node:sqlite行为一致每个连接先设 5 秒busy_timeout打开已就绪的库不拿写锁因此多个 Agent 宿主OpenCode、Pi、OMP可以同时启动而互不排队。 两个库是一个一致性单元任何一侧的权威与镜像状态都引用对方备份/回滚时必须成对操作。完整说明见官方文档 storage.md。二、Schema 与版本栅栏为什么升级不炸库这是 Magic Context 存储层最硬核的设计核心只有一句话版本必须锁步lockstep对不上就拒绝打开数据库。关键规则LATEST_SUPPORTED_VERSION是唯一事实来源定义在 storage-db.ts当前值为94它必须与 migrations.ts 中最新版本号相等锁步测试schema-version-fence.test.ts强制两者同步移动Fail-closed失败即关闭如果构建能理解的版本低于库里实际版本进程拒绝打开库并进入保护状态——每次主变换直接抛出可恢复错误而不是让提示词失控增长或悄悄回退到原生压缩迁移时机守卫若仍有运行旧版本插件的宿主进程占着库迁移会被拒绝并记录日志避免新库 旧进程的组合版本车道version lanes10000的版本号保留给上游 Magic Context≥10000预留给共享context.db的分支插件两条互不干扰规则见 migration-version-lanes.md。加一个新迁移的 5 步标准动作在 migrations.ts 追加下一版本并配一份migrations-vN.test.ts把LATEST_SUPPORTED_VERSION抬到同一数字忘了这步 迁移后数据库拒绝打开同步更新storage-db.ts里的全新安装 schema让新库直接落到最终形态无需重放全部迁移用 storage-schema-helpers.ts 中的ensureColumn/healAllNullColumns兜底老库即使丢了迁移记录也能补齐列、回填默认值若表按会话隔离登记进SESSION_SCOPED_TABLES否则删除会话时该行会永久泄漏。三、核心表速览谁管记忆谁管会话Rust 侧的store.db迁移链定义在 lib.rs从中可以摘出几张最有代表性的表表名作用一句话mc_cache_state每会话的持久缓存状态带row_version乐观并发控制mc_compartments区室历史会话被切成记忆单元含多档复述层 p1–p4 与重要度衰减率mc_memories项目记忆主表UNIQUE(project_path, category, normalized_hash)去重被替换的记忆用superseded_by_memory_id记录mc_memory_mutation_log只追加的变更日志归档/删除/更新不重渲基线而是以小 delta 补丁下发保护提示词缓存mc_user_memories跨项目的用户画像记忆user-profile基线来源mc_workspaces/mc_workspace_members跨项目工作区成员项目可共享指定分类的记忆mc_pass_trace/mc_chunk_transcripts每次变换的接收/完成/拒绝审计痕迹可恢复的压缩转录表分两类会话级带harness列区分宿主如pi/opencode与项目级刻意跨宿主共享——从 Pi 写入的记忆同一项目下 OpenCode 也能读到。删除会话与孤儿清扫都依赖 storage-session-tables.ts 里的完整清单。四、稳定项目身份记忆为何不会丢记忆按什么键归档直接存路径是最朴素的答案也是最大的坑——移动目录、符号链接、大小写差异都会让记忆失联。Magic Context 的答案在 project_identity.rs一个目录在context.db中用一个身份而不是路径来标识有 git 历史的检出是git:根提交哈希否则是dir:路径 MD5 前 12 位。这套算法的巧妙之处git:身份永不变化取git rev-list --max-parents0 HEAD的根提交哈希多条无关历史取字典序最小目录怎么挪、换什么名字记忆池始终跟得上且结果永久缓存dir:身份每 5 分钟复检因为目录后来可能git init成仓库需要升级为git:身份故障时的降级策略git 临时不可用超时、二进制缺失时复用该目录或其同仓库祖先最后一次成功的git:身份绝不落到dir:——否则会为同一个检出生成别人不会计算的新身份记忆被拆成两个池子宿主侧记忆文件宿主每次 git 探测成功后把身份写到context.db旁边的project-identities/边车文件中Rust 模块直接复用保证两条代码路径算出完全相同的值家目录不算项目allowHomeProject关闭时直接拒绝避免把生活记进记忆库。 一句话总结身份稳定记忆才稳定——这是Memory that manages itself的底层前提。五、迁移机制从双库到单库的一次性大手术context.db与store.db曾经并行存两份项目记忆靠镜像机制保持同步。如今这套镜像已退役迁移 61定义于 single_store_schema.rs把所有领域表搬进context.db并删除旧表。迁移引擎实现于 single_store_migrate.rs流程堪称教科书级先备份两个文件都快照到备份目录并在任何写入前打印目录位置切到 rollback-journal 模式SQLite 只有在非 WAL 模式下才能对 ATTACH 的多个库做跨文件原子提交这步保证拷贝、标记、缓存重置要么全成要么全败一个BEGIN IMMEDIATE横跨两文件建表 → 逐项目分类拷贝 → 重置模块缓存 → 清除镜像/权威表 →验证包括从两边分别渲染 m0 基线且必须逐字节一致的渲染检查→ 才删旧表、写入共享的迁移印章任何拒绝或错误都回滚两个文件还支持--dry-run走完全流程后原样回退。用户侧只需要一条命令退出所有宿主后magic-context doctor single-store migrate如果两个库对是否已迁移说法不一模块会以稳定的错误令牌single_store_state_split拒绝服务并给出明确指引而不是带着脏数据继续跑。六、备份与修复日常运维清单备份backup-live-stores.sh 用VACUUM INTO快照context.db和store.db——单事务内读取、不拿写锁会话正在写入也能得到一致副本每份快照附带完整性校验与 schema 版本恢复时可精确匹配构建的栅栏版本恢复停掉所有占用进程 → 删除-wal/-shm文件 → 用快照覆盖两个库都要→ 只启动一个宿主修复npx cortexkit/magic-context doctor repair-db修复损坏的context.db动手前先把坏文件打包成.corrupt-backup-时间戳。七、小结三层防线撑起一生的会话层机制解决的问题版本层栅栏 锁步 失败即关闭新库旧构建互不踩坑身份层git:/dir:稳定项目身份记忆跨目录、跨宿主管线复用迁移层跨文件单事务 渲染级验证 全量备份双库合一无数据丢失想继续深入推荐按这个顺序阅读storage.md存储总览→ rust-module.mdRust 模块与回滚→ migrations.ts迁移全景。看懂这套存储层你就理解了 Magic Context 为何敢承诺一个会话用一生。【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-context创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考