Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* MemoryStorage — Maker Memory 的文件系统层 (CRUD + frontmatter + MEMORY.md 派生)。
*
* 责任边界:
* - 文件 IO + frontmatter 解析 + 路径 sanitize + size 校验
* - **MEMORY.md 索引由本层自动重建** (write/delete 时同步触发), LLM 永远不直接改 MEMORY.md
* → 跟 Claude Code auto-memory "让 LLM 手写索引" 的反 pattern 区分; 解决 "分片改了
* 但索引没同步" 的常见 bug。
* - 不管 SQLite/FTS5 (那是 fts.ts 的事), 不管 BaseAgent / MCP (那是上层的事)。
* - 不管 sanitizeWorkdir → directory name 的映射, 调用方传已经准备好的目录绝对路径。
*
* 写入路径:
* write() → schema 校验 → 撞名/size 检查 → 写 .md 文件 → rebuildIndex() → 返 WriteResult
* 失败抛 MemoryError (硬错误: schema/撞名/路径非法), 软警告通过 WriteResult.warning 字段
* 返给调用方 (size 接近上限, 提示 LLM consolidate)。
*
* 时序:
* 同一宿主进程内按目录串行写入与删除,界面版本检查和伙伴工具写入共享互斥。
* 不宣称保护外部编辑器或其它进程直接修改文件。
*/
import { createHash } from 'node:crypto';
import { promises as fs } from 'node:fs';
import * as path from 'node:path';
import matter from 'gray-matter';
import {
CURATED_MEMORY_TYPES,
DEFAULT_MEMORY_CONFIG,
isMemoryType,
MemoryError,
type MemoryConfig,
type MemoryFrontmatter,
type MemoryRecord,
type MemoryType,
type WriteOptions,
type WriteResult,
type WriteWarningDetail,
} from './types.js';
const INDEX_FILENAME = 'MEMORY.md';
const META_FILENAME = 'meta.json';
const SHARD_EXT = '.md';
const SLUG_REGEX = /^[a-z0-9_-]+$/;
// Multiple store instances for the same directory must share the mutation queue.
const mutationQueues = new Map<string, Promise<unknown>>();
/**
* 把 workdir 绝对路径转成 sanitize 后的目录名 (Claude Code 风格)。
* E:\AIWork\xdt-maker → 'E--AIWork-xdt-maker'
* /Users/sam/proj → 'Users-sam-proj'
*
* 用法是 host 算好后传给 MakerMemoryStore: <userData>/maker-memory/<sanitized>/。
* 不在 storage 里直接拼路径, 保持 storage 的 dir 是 "已就绪的目录" 这一职责单一。
*/
export function sanitizeWorkdir(absPath: string): string {
// 替换路径分隔符 + 冒号 (Windows 盘符) 为 '-'; 去除前导 '-' 但保留 'E--' 这种
// 双 dash (盘符自带 ':' → '-' + '\' → '-')。
return absPath
.replace(/[\\/]/g, '-')
.replace(/:/g, '-')
.replace(/^-+/, ''); // 去除最前面的 leading '-' (Unix 路径 / 开头转完是 '-Users-...')
}
/**
* Maker Memory 的 store 定位键(scope key)。本地会话直接用 workdir 绝对路径
* (保持既有存储目录不迁移);SSH remote 会话用 `ssh:<host 段>:<workdir>` 复合键 —
* 远端路径是远端机器上的字符串,直接当 key 会跟本地同名路径共用一个 store
* (两台机器各有 /home/me/proj 时记忆互串)。host 段经 encodeURIComponent 编码:
* 编码后不含 `:`,前缀后的首个 `:` 即边界,(hostId, workdir) → key 是单射 —
* 裸拼接时 ('/x:/repo','prod') 与 ('/repo','prod:/x') 会撞成同一个 key
* (review R5 P2);常规 alias 编码前后相同,键仍可读。数据仍存控制端本机,
* 目录名经 memoryScopeDirName 派生。所有 getStore 调用方 (agent 启动注入 /
* MCP withStore) 必须统一取键,不得各自拼接——**统一入口是 async 的
* resolveMemoryScopeKey (scope-resolver.ts)**: 它在本地会话上额外做 git
* linked-worktree 归一化 (#2379), 本函数保持同步原契约不变。
*/
export function buildMemoryScopeKey(workingDir: string, remoteHostId?: string | null): string {
return remoteHostId ? `ssh:${encodeURIComponent(remoteHostId)}:${workingDir}` : workingDir;
}
/**
* Cindy Bot 的长期记忆作用域。
*
* Bot 可以在多个项目、route 和远端 Host 上工作;用 workingDir 分区会让同一个 Bot
* 的记忆被切碎,也会让两个 Bot 在同一项目里互相污染。Profile runtime 因此把
* Bot id 映射成独立且稳定的 scope key,所有 harness prompt 与 cindy_memory MCP
* 都使用同一个 key。
*/
export function buildBotMemoryScopeKey(botId: string): string {
if (!botId.trim()) throw new Error('buildBotMemoryScopeKey: botId required');
return `bot:${encodeURIComponent(botId.trim())}`;
}
/**
* Reverse a Bot memory scope without teaching the generic memory manager about
* Desktop's Bot Home layout. Invalid/non-Bot keys return null and therefore
* remain ordinary Maker Memory scopes.
*/
export function parseBotMemoryScopeKey(scopeKey: string): string | null {
if (!scopeKey.startsWith('bot:')) return null;
const encoded = scopeKey.slice('bot:'.length);
if (!encoded) return null;
try {
const botId = decodeURIComponent(encoded).trim();
return botId || null;
} catch {
return null;
}
}
/** buildMemoryScopeKey 的远端键前缀。本地键恒为绝对路径, 不会以它开头。 */
export const SSH_SCOPE_KEY_PREFIX = 'ssh:';
const BOT_SCOPE_KEY_PREFIX = 'bot:';
/**
* scope key → 落盘目录名。本地键沿用 sanitizeWorkdir(既有目录不迁移);远端
* 键不能走有损的 sanitizeWorkdir — `ssh:prod:/repo` 与本地路径 `/ssh/prod:/repo`
* 会 sanitize 成同一个目录名, 隔离承诺被撞破 (review R4 P2)。远端目录名 =
* `ssh-<host 可读片段>-<sha256(完整 key) 前 16 hex>`:key 是 (hostId, 路径)
* 对的单射 (见 buildMemoryScopeKey), hash 因此保证目录唯一性, 且对特殊字符/
* 超长路径免疫 (定长, Windows MAX_PATH 安全);host 片段 (编码形态, 不含 `:`)
* 只为肉眼可辨识。
*/
export function memoryScopeDirName(scopeKey: string): string {
if (scopeKey.startsWith(BOT_SCOPE_KEY_PREFIX)) {
const botSegment = scopeKey.slice(BOT_SCOPE_KEY_PREFIX.length);
const digest = createHash('sha256').update(scopeKey, 'utf8').digest('hex').slice(0, 16);
return `bot-${sanitizeWorkdir(botSegment).slice(0, 24)}-${digest}`;
}
if (!scopeKey.startsWith(SSH_SCOPE_KEY_PREFIX)) return sanitizeWorkdir(scopeKey);
const hostSegment = scopeKey.slice(SSH_SCOPE_KEY_PREFIX.length).split(':', 1)[0] ?? '';
const digest = createHash('sha256').update(scopeKey, 'utf8').digest('hex').slice(0, 16);
return `ssh-${sanitizeWorkdir(hostSegment).slice(0, 24)}-${digest}`;
}
/** filename = `<type>_<slug>.md`; slug 误带 `<type>_` 前缀会被拒绝 (见 validateNoTypePrefix) */
export function buildFilename(type: MemoryType, slug: string): string {
validateNoTypePrefix(type, slug);
return `${type}_${slug}${SHARD_EXT}`;
}
/**
* 拒绝 slug 上误带的 `<type>_` 前缀 — memory_write 的调用方 (LLM) 常把 type
* 写进 name, 造成 `feedback_feedback_foo.md` 双前缀分片 (#1652 附带 bug, #205 审计亦命中)。
* **只报错不剥离**: 剥离会让存量双前缀分片在 update/append/consolidate 时定位错位 —
* parseFilename 把 `feedback_feedback_foo.md` 的 slug 解析为 `feedback_foo`, 剥离后
* 定位到 `feedback_foo.md`, 造成 not-found 或静默修改错误分片。报错让调用方传纯 slug,
* 存量双前缀分片由一次性改名/去重迁移清理 (另行处理)。
*/
function validateNoTypePrefix(type: MemoryType, slug: string): void {
if (slug === type) {
throw new MemoryError(
'invalid-slug',
`slug 不能等于 type 名 "${type}", 请传纯 slug (如 "${type}-brief")`,
);
}
if (slug.startsWith(`${type}_`)) {
throw new MemoryError(
'invalid-slug',
`slug "${slug}" 已带 type 前缀 "${type}_", 请传纯 slug (如 "${stripAllTypePrefixes(type, slug) || type + '-brief'}")`,
);
}
}
/** 剥掉 slug 上所有重复的 `<type>_` 前缀 — 错误信息示例必须本身可通过校验 */
function stripAllTypePrefixes(type: MemoryType, slug: string): string {
let out = slug;
while (out.startsWith(`${type}_`)) {
out = out.slice(type.length + 1);
}
return out;
}
/** 解析 filename 反推 type + slug, 不匹配返 null */
export function parseFilename(filename: string): { type: MemoryType; slug: string } | null {
if (!filename.endsWith(SHARD_EXT)) return null;
if (filename === INDEX_FILENAME) return null;
const stem = filename.slice(0, -SHARD_EXT.length);
const idx = stem.indexOf('_');
if (idx <= 0) return null;
const typeStr = stem.slice(0, idx);
const slug = stem.slice(idx + 1);
if (!isMemoryType(typeStr)) return null;
if (!SLUG_REGEX.test(slug)) return null;
return { type: typeStr, slug };
}
export function validateSlug(slug: string, maxLen: number): void {
if (!SLUG_REGEX.test(slug)) {
throw new MemoryError('invalid-slug', `slug 只允许 [a-z0-9_-], 收到 "${slug}"`);
}
if (slug.length > maxLen) {
throw new MemoryError('invalid-slug', `slug 长度 > ${maxLen}: "${slug}"`);
}
}
export interface MemoryStorageMeta {
/** workdir 绝对路径 (调用方记录, storage 不解析) */
absPath: string;
/** 首次创建时间 (ISO) */
createdAt: string;
/** 最近一次写/读时间 (ISO) — manager 决定是否更新 */
lastUsedAt: string;
}
export class MemoryStorage {
private indexCache: string | null = null;
/**
* 派生索引 (MEMORY.md) 失效标记 (review #2388 Codex 23rd P1/P2): shard
* write/delete 已落盘但其后的 rebuildIndex 被 owner 边界中止时置位 —
* 文件与索引不一致; 下次安全打开 (init) 时 repairIndexIfDirty 惰性修复,
* 防止同 owner 后续 session 把 stale 索引读进 system prompt。
*/
private derivedIndexDirty = false;
constructor(
/** 已就绪的目录绝对路径, e.g. <userData>/maker-memory/<sanitized-workdir>/ */
public readonly dir: string,
public readonly config: MemoryConfig = DEFAULT_MEMORY_CONFIG,
/**
* 文件系统写入前守卫 (review #2388 Codex 8th P1): write 内部在真正写盘前
* 有 await (tryReadRaw 读现有文件判 mode), 边界可在此窗口发生 — 必须在该
* await 之后、fs.writeFile 之前复核 owner scope, 否则直接调用方 (如 Pi
* compaction 经 manager.write, withStore 后置检查之外) 会把写入落到旧
* owner 根后报成功。由 store 透传 manager 注入的 scopeCheck。
*/
private readonly beforeFileWrite?: () => void,
) {}
/** mkdir -p + 写 meta.json (如缺失). 幂等。 */
async init(absWorkdir: string): Promise<void> {
await fs.mkdir(this.dir, { recursive: true });
const metaPath = path.join(this.dir, META_FILENAME);
try {
await fs.access(metaPath);
} catch {
// 首次打开副作用也 fail-closed (review #2388 Codex 16th P1): 异步初始化
// 期间边界发生, 不得在旧 owner 下创建 meta.json。
this.beforeFileWrite?.();
const meta: MemoryStorageMeta = {
absPath: absWorkdir,
createdAt: new Date().toISOString(),
lastUsedAt: new Date().toISOString(),
};
await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf8');
}
}
/**
* 列出所有 memory 分片 (含 frontmatter + body)。MEMORY.md / meta.json 自动跳过。
* 损坏文件 (frontmatter 缺失 / type 非法) 跳过 + 不抛错 — 不让单个坏文件拖垮全量列表。
*/
async list(): Promise<MemoryRecord[]> {
let entries: string[];
try {
entries = await fs.readdir(this.dir);
} catch (e) {
if (isENOENT(e)) return [];
throw new MemoryError('io-error', `readdir failed: ${(e as Error).message}`);
}
const records: MemoryRecord[] = [];
for (const entry of entries) {
if (entry === INDEX_FILENAME || entry === META_FILENAME) continue;
if (!entry.endsWith(SHARD_EXT)) continue;
const parsed = parseFilename(entry);
if (!parsed) continue;
try {
const rec = await this.readRecord(entry);
if (rec) records.push(rec);
} catch {
// 单个坏文件跳过, 由 review 工具后续清理
}
}
// 按 type 分组, 同 type 内按 slug 升序 → MEMORY.md 索引可读性
records.sort((a, b) => {
if (a.frontmatter.type !== b.frontmatter.type) {
return a.frontmatter.type.localeCompare(b.frontmatter.type);
}
return a.slug.localeCompare(b.slug);
});
return records;
}
/** 读单条; 不存在抛 not-found; 损坏抛 invalid-frontmatter */
async read(filename: string): Promise<MemoryRecord> {
this.assertSafeFilename(filename);
const rec = await this.readRecord(filename);
if (!rec) throw new MemoryError('not-found', `memory not found: ${filename}`);
return rec;
}
/**
* 写入. mode 语义:
* - 'create' (默认): 撞名抛 already-exists
* - 'update' : 覆盖, 不存在抛 not-found
* - 'append' : 追加 body 到现有末尾, 不存在抛 not-found
*
* 写完自动重建 MEMORY.md。返 WriteResult.warning:
* - 'shard-size-exceeded' : 写完后 body 超 maxShardBytes (软上限)
* - 'index-size-exceeded' : 重建后 MEMORY.md 超 maxIndexBytes (软上限)
* 软警告 = 写入仍成功; warningDetail 附当前字节/软上限/硬上限,
* 调用方据此判断超了多少再决定不动 / 微剪 / consolidate。
*/
async write(opts: WriteOptions): Promise<WriteResult> {
this.validateOpts(opts);
return this.mutate(() => this.writeFile(opts, buildFilename(opts.type, opts.name)));
}
/** Edit a known file in place, including legacy names rejected for new shards. */
async update(
filename: string,
expectedUpdatedAt: string,
changes: Pick<WriteOptions, 'title' | 'description' | 'body'>,
): Promise<MemoryRecord> {
return this.mutate(async () => {
const current = await this.checkVersion(filename, expectedUpdatedAt);
await this.writeFile({
...changes, type: current.frontmatter.type, name: current.slug, mode: 'update',
}, filename);
// Return the revision this edit wrote, never a subsequent tool write.
return this.read(filename);
});
}
private async mutate<T>(run: () => Promise<T>): Promise<T> {
const key = path.resolve(this.dir);
const previous = mutationQueues.get(key) ?? Promise.resolve();
const next = previous.catch(() => {}).then(run);
mutationQueues.set(key, next);
try {
return await next;
} finally {
if (mutationQueues.get(key) === next) mutationQueues.delete(key);
}
}
private async checkVersion(filename: string, expected: string): Promise<MemoryRecord> {
const current = await this.read(filename);
if (current.frontmatter.updatedAt !== expected) {
throw new MemoryError('version-conflict', 'Memory changed since it was opened');
}
return current;
}
private async writeFile(opts: WriteOptions, filename: string): Promise<WriteResult> {
this.validateOpts(opts);
const fullPath = path.join(this.dir, filename);
let nextBody = opts.body;
let preserveBody = opts.preserveBody === true;
let nextFrontmatter: MemoryFrontmatter;
const mode = opts.mode ?? 'create';
const existing = await this.tryReadRaw(fullPath);
if (mode === 'create') {
if (existing) {
throw new MemoryError(
'already-exists',
`${filename} 已存在; 用 mode:'update' 覆盖或 mode:'append' 追加`,
);
}
nextFrontmatter = {
title: opts.title,
description: opts.description,
type: opts.type,
updatedAt: new Date().toISOString(),
};
} else {
if (!existing) {
throw new MemoryError('not-found', `${filename} 不存在; 用 mode:'create' 新建`);
}
const parsed = parseRawShard(existing, filename);
// Editing an imported shard must not silently downgrade its exact-body
// format; import retries still need to detect whitespace-only edits.
preserveBody ||= parsed.frontmatter.bodyLength !== undefined;
if (mode === 'append') {
nextBody = `${parsed.body.trimEnd()}\n\n${opts.body}`;
}
nextFrontmatter = {
title: opts.title || parsed.frontmatter.title,
description: opts.description || parsed.frontmatter.description,
type: opts.type,
// A second write in the same millisecond must still invalidate old editors.
updatedAt: new Date(Math.max(Date.now(), (Date.parse(parsed.frontmatter.updatedAt) || 0) + 1)).toISOString(),
};
}
// size 硬上限校验 (写之前)
if (Buffer.byteLength(nextBody, 'utf8') > this.config.hardShardBytes) {
throw new MemoryError(
'shard-too-large',
`body ${Buffer.byteLength(nextBody, 'utf8')} bytes > 硬上限 ${this.config.hardShardBytes}`,
);
}
if (preserveBody) nextFrontmatter.bodyLength = nextBody.length;
const fileText = matter.stringify({ content: nextBody }, nextFrontmatter);
// tryReadRaw 的 await 窗口后、真正写盘前复核 owner scope (review #2388
// Codex 8th P1): 边界不得把 shard 写入旧 owner 根。
this.beforeFileWrite?.();
await fs.writeFile(fullPath, fileText, 'utf8');
// shard write 后、索引重建前复核 (review #2388 Codex 12th P1): writeFile
// await 期间边界可能发生, 不得继续在旧 owner 下 rebuildIndex / 返回成功。
// not-ready 时文件已落盘但 MEMORY.md 未更新 → 标记派生索引 dirty (Codex 23rd)。
this.guardAfterMutation();
await this.rebuildIndex();
// rebuildIndex 自身多次 await 后、返回前复核 (review #2388 Codex 13th P1)。
this.beforeFileWrite?.();
const result: WriteResult = { ok: true, filename };
const detail = this.computeWarning(nextBody);
if (detail) {
result.warning = detail.kind;
result.warningDetail = detail;
}
return result;
}
async delete(filename: string, expectedUpdatedAt?: string): Promise<void> {
return this.mutate(async () => {
if (expectedUpdatedAt !== undefined) await this.checkVersion(filename, expectedUpdatedAt);
await this.deleteFile(filename);
});
}
private async deleteFile(filename: string): Promise<void> {
this.assertSafeFilename(filename);
const fullPath = path.join(this.dir, filename);
// 删除前复核 (review #2388 Codex 14th P1): 单次预检只保护 delete 开始瞬间,
// 边界在 fs.unlink / rebuildIndex 之间发生仍会删旧 owner 文件并重建索引。
this.beforeFileWrite?.();
try {
await fs.unlink(fullPath);
} catch (e) {
if (isENOENT(e)) throw new MemoryError('not-found', `${filename} 不存在`);
throw new MemoryError('io-error', `unlink failed: ${(e as Error).message}`);
}
// unlink 后复核 — await 窗口后边界可能发生, 不得继续在旧 owner 下重建索引。
// not-ready 时文件已删但 MEMORY.md 仍列出 → 标记派生索引 dirty (Codex 23rd)。
this.guardAfterMutation();
await this.rebuildIndex();
// rebuildIndex 内部多次 await 后、返回前复核。
this.beforeFileWrite?.();
}
/**
* 变更后复核辅助 (review #2388 Codex 23rd P1/P2): shard 已落盘但其后
* rebuildIndex 被 owner 边界中止 → 文件与 MEMORY.md 不一致, 标记派生索引
* dirty; 下次安全打开 (init) 时 repairIndexIfDirty 惰性重建, 防止同 owner
* 后续 session 把 stale 索引读进 system prompt。
*/
private guardAfterMutation(): void {
try {
this.beforeFileWrite?.();
} catch (e) {
if (e instanceof MemoryError && e.code === 'not-ready') {
this.derivedIndexDirty = true;
this.indexCache = null;
}
throw e;
}
}
private markIndexDirty(): void {
this.derivedIndexDirty = true;
this.indexCache = null;
}
/** 派生索引 (MEMORY.md) 是否因中止的写/删而失效 */
isIndexDirty(): boolean {
return this.derivedIndexDirty;
}
/** 惰性修复: 上次变更被边界中止 → 重建 MEMORY.md 恢复一致 (幂等) */
async repairIndexIfDirty(): Promise<void> {
if (!this.derivedIndexDirty) return;
await this.rebuildIndex();
this.derivedIndexDirty = false;
}
/** 当前 MEMORY.md 内容 (索引文本, 给 system prompt 拼). 不存在返空串 */
async getIndex(): Promise<string> {
if (this.indexCache !== null) return this.indexCache;
try {
this.indexCache = await fs.readFile(path.join(this.dir, INDEX_FILENAME), 'utf8');
return this.indexCache;
} catch (e) {
if (isENOENT(e)) {
this.indexCache = '';
return '';
}
throw new MemoryError('io-error', `read index failed: ${(e as Error).message}`);
}
}
/**
* 重建 MEMORY.md (从所有分片 frontmatter 派生). 调用方一般不直接用 — write/delete 自动触发。
* 索引格式:
* # Memory Index
*
* ## user
* - [user_xxx.md] 用户偏好 — 一行 hook description
* ...
*
* ## feedback
* ...
*/
async rebuildIndex(): Promise<void> {
try {
await this.rebuildIndexInner();
} catch (e) {
// 重建被 owner 边界中止 → 索引未更新, 标记 dirty (review #2388 Codex 23rd)
if (e instanceof MemoryError && e.code === 'not-ready') {
this.markIndexDirty();
}
throw e;
}
}
private async rebuildIndexInner(): Promise<void> {
const records = await this.list();
const grouped = new Map<MemoryType, MemoryRecord[]>();
for (const rec of records) {
const arr = grouped.get(rec.frontmatter.type) ?? [];
arr.push(rec);
grouped.set(rec.frontmatter.type, arr);
}
const lines: string[] = ['# Memory Index', ''];
if (records.length === 0) {
lines.push('_(empty — no memories saved yet for this workdir)_', '');
} else {
// 固定顺序 user → feedback → project → reference。**只列 curated 类型** ——
// `digest`(系统内部,如 pi 压缩摘要)故意排除:进 FTS 可 memory_search,但不进
// MEMORY.md、不进 system prompt(见 types.ts MEMORY_TYPES 注释)。新增 curated
// 类型时改 CURATED_MEMORY_TYPES;不要把 digest 加进来。
for (const type of CURATED_MEMORY_TYPES) {
const items = grouped.get(type);
if (!items || items.length === 0) continue;
lines.push(`## ${type}`);
for (const r of items) {
lines.push(`- [${r.filename}] ${r.frontmatter.title} — ${r.frontmatter.description}`);
}
lines.push('');
}
}
const content = lines.join('\n');
// 索引写盘前复核 (review #2388 Codex 13th P1): rebuildIndex 自身有多次
// awaited shard reads, 边界不得在旧 owner 下重写 MEMORY.md。
this.beforeFileWrite?.();
await fs.writeFile(path.join(this.dir, INDEX_FILENAME), content, 'utf8');
this.indexCache = content;
}
/** 当前索引字节数 (UI / warning 用) */
async getIndexSize(): Promise<number> {
const content = await this.getIndex();
return Buffer.byteLength(content, 'utf8');
}
// ── 内部 helper ────────────────────────────────────────────────────────────
private validateOpts(opts: WriteOptions): void {
if (!isMemoryType(opts.type)) {
throw new MemoryError('invalid-type', `type 必须是 user/feedback/project/reference, 收到 "${opts.type}"`);
}
validateSlug(opts.name, this.config.maxSlugLen);
if (!opts.title || opts.title.length === 0) {
throw new MemoryError('invalid-frontmatter', 'title 必填');
}
if (opts.title.length > this.config.maxTitleLen) {
throw new MemoryError('title-too-long', `title 长度 > ${this.config.maxTitleLen}`);
}
if (!opts.description || opts.description.length === 0) {
throw new MemoryError('invalid-frontmatter', 'description 必填');
}
if (opts.description.length > this.config.maxDescriptionLen) {
throw new MemoryError(
'description-too-long',
`description 长度 > ${this.config.maxDescriptionLen}`,
);
}
if (/\r|\n/.test(opts.description)) {
throw new MemoryError('description-has-newline', 'description 必须是一行 (无换行)');
}
if (!opts.body || opts.body.length === 0) {
throw new MemoryError('invalid-frontmatter', 'body 必填');
}
}
private assertSafeFilename(filename: string): void {
if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
throw new MemoryError('path-traversal', `非法文件名: "${filename}"`);
}
const parsed = parseFilename(filename);
if (!parsed) {
throw new MemoryError('invalid-filename', `不符合 <type>_<slug>.md 格式: "${filename}"`);
}
}
private async readRecord(filename: string): Promise<MemoryRecord | null> {
const parsed = parseFilename(filename);
if (!parsed) return null;
const fullPath = path.join(this.dir, filename);
const raw = await this.tryReadRaw(fullPath);
if (!raw) return null;
const shard = parseRawShard(raw, filename);
if (!shard) return null;
return {
filename,
slug: parsed.slug,
frontmatter: shard.frontmatter,
body: shard.body,
sizeBytes: Buffer.byteLength(raw, 'utf8'),
};
}
private async tryReadRaw(fullPath: string): Promise<string | null> {
try {
return await fs.readFile(fullPath, 'utf8');
} catch (e) {
if (isENOENT(e)) return null;
throw new MemoryError('io-error', `read failed: ${(e as Error).message}`);
}
}
/**
* 重算某分片的软警告 (含索引侧)。分片侧读盘; 索引侧走 indexCache —
* 本实例的 write/delete 都会刷新缓存, 因此反映的是**本实例视角**的最新状态;
* 若 MEMORY.md 被其他实例/进程改写, 索引侧评估可能滞后。
* consolidate 删源后索引已变小, 写入时点的警告可能失真 — 收尾用本方法重算。
*/
async assessWarning(filename: string): Promise<WriteWarningDetail | undefined> {
const rec = await this.read(filename);
await this.getIndex(); // 确保 indexCache 就绪 (新实例上也能评估索引侧)
return this.computeWarning(rec.body);
}
private computeWarning(body: string): WriteWarningDetail | undefined {
const bodyBytes = Buffer.byteLength(body, 'utf8');
if (bodyBytes > this.config.maxShardBytes) {
return {
kind: 'shard-size-exceeded',
sizeBytes: bodyBytes,
softLimitBytes: this.config.maxShardBytes,
hardLimitBytes: this.config.hardShardBytes,
};
}
// 索引刚被 rebuildIndex 写过, 直接读 cache
const indexBytes =
this.indexCache !== null ? Buffer.byteLength(this.indexCache, 'utf8') : 0;
if (indexBytes > this.config.maxIndexBytes) {
return {
kind: 'index-size-exceeded',
sizeBytes: indexBytes,
softLimitBytes: this.config.maxIndexBytes,
};
}
return undefined;
}
}
// ── 模块级工具 ─────────────────────────────────────────────────────────────
interface ParsedShard {
frontmatter: MemoryFrontmatter;
body: string;
}
function parseRawShard(raw: string, filenameForErr: string): ParsedShard {
const parsed = matter(raw);
const data = parsed.data as Partial<MemoryFrontmatter>;
if (!data.title || !data.description || !isMemoryType(data.type)) {
throw new MemoryError(
'invalid-frontmatter',
`${filenameForErr} frontmatter 缺字段或 type 非法`,
);
}
return {
frontmatter: {
title: data.title,
description: data.description,
type: data.type,
updatedAt: typeof data.updatedAt === 'string' ? data.updatedAt : new Date().toISOString(),
...(Number.isSafeInteger(data.bodyLength) && data.bodyLength! >= 0 ? { bodyLength: data.bodyLength } : {}),
},
// gray-matter appends one newline. Remove only that exact serialization
// suffix; an external edit must never be truncated to a stale length.
body: Number.isSafeInteger(data.bodyLength) && data.bodyLength! >= 0
? (parsed.content.length === data.bodyLength! + 1 && parsed.content.endsWith('\n')
? parsed.content.slice(0, -1) : parsed.content)
: parsed.content.trim(),
};
}
function isENOENT(e: unknown): boolean {
return typeof e === 'object' && e !== null && (e as { code?: string }).code === 'ENOENT';
}