05 — 进阶设计亮点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// tag-stripping.ts L4-11
const TAG_NAMES = [
  'private',
  'claude-mem-context',
  'system_instruction',
  'system-instruction',
  'persisted-output',
  'system-reminder',
] as const;

const STRIP_REGEX = new RegExp(
  `<(${TAG_NAMES.join('|')})\\b[^>]*>[\\s\\S]*?</\\1>`,
  'g'
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

用户输入 ─── UserPromptSubmit Hook ──→ session-init.ts
                                         │
                          isInternalProtocolPayload() 检测
                          （如果整个 prompt 是协议包，直接跳过，不记录）
                                         │
                                         ▼
                               Worker /api/sessions/init
                                         │
                          PrivacyCheckValidator.checkUserPromptPrivacy()
                          （如果 prompt 去掉 <private> 后为空 → 整条跳过）
                                         │
                                         ▼
                          stripMemoryTagsFromJson(toolInput/toolResponse)
                          （记录到 DB 前最终清洁）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// shared.ts L142-151：Worker 层的隐私防线
const userPrompt = PrivacyCheckValidator.checkUserPromptPrivacy(
  store, contentSessionId, promptNumber, 'observation', sessionDbId
);
if (!userPrompt) {
  return { ok: true, status: 'skipped', reason: 'private' };  // 直接跳过，不进队列
}

// shared.ts L154-158：写 DB 前最终清洁
const cleanedToolInput = payload.toolInput !== undefined
  ? stripMemoryTagsFromJson(JSON.stringify(payload.toolInput))
  : '{}';

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// tag-stripping.ts L56-68
const PROTOCOL_ONLY_REGEX = new RegExp(
  `^\\s*<(${PROTOCOL_ONLY_TAGS.join('|')})\\b[^>]*>(?:(?!<\\1\\b|</\\1\\b)[\\s\\S])*</\\1>\\s*$`,
);

export function isInternalProtocolPayload(text: string): boolean {
  if (!text) return false;
  if (text.length > MAX_PROTOCOL_PAYLOAD_BYTES) return false;  // 256KB 硬上限
  return PROTOCOL_ONLY_REGEX.test(text);
}

1
2
3
4

CorpusStore        ← 文件系统持久化（.corpus.json）
CorpusBuilder      ← 从 SQLite 查询 + 过滤 → 构建 CorpusFile
CorpusRenderer     ← CorpusFile → Markdown 文本（用于 AI 上下文）
KnowledgeAgent     ← 调用 Claude Agent SDK，prime/query/reprime

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// CorpusBuilder.ts L37-99
async build(name: string, description: string, filter: CorpusFilter): Promise<CorpusFile> {
  // Step 1: 用 SearchOrchestrator 做语义/关键字搜索，得到 observation IDs
  const searchResult = await this.searchOrchestrator.search(searchArgs);
  const observationIds = searchResult.results.observations.map(obs => obs.id);

  // Step 2: 按 ID 批量 hydrate，按时间正序
  const observationRows = this.sessionStore.getObservationsByIds(observationIds, {
    orderBy: 'date_asc'  // 知识库里时间线从旧到新，方便 AI 理解演进
  });

  // Step 3: 映射为 CorpusObservation，计算 stats（类型分布/时间跨度）
  const observations = observationRows.map(row => this.mapObservationToCorpus(row));

  // Step 4: 生成 SystemPrompt（告知 AI 这个知识库的 scope 和规则）
  corpus.system_prompt = this.renderer.generateSystemPrompt(corpus);

  // Step 5: 估算 token 数（字符数 / 4）
  corpus.stats.token_estimate = this.renderer.estimateTokens(renderedText);

  this.corpusStore.write(corpus);  // 写到 ~/.claude-mem/corpora/<name>.corpus.json
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "version": 1,
  "name": "auth-refactor",
  "description": "...",
  "filter": { "project": "my-app", "types": ["decision", "bugfix"] },
  "stats": {
    "observation_count": 42,
    "token_estimate": 18500,
    "date_range": { "earliest": "...", "latest": "..." },
    "type_breakdown": { "decision": 10, "bugfix": 32 }
  },
  "system_prompt": "You are a knowledge agent...",
  "session_id": "abc123",      // Claude Agent SDK 会话 ID，null 时需要 prime
  "observations": [...]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// KnowledgeAgent.ts L39-97
async prime(corpus: CorpusFile): Promise<string> {
  const primePrompt = [
    corpus.system_prompt,               // "你是一个有42条观察的知识 agent"
    'Here is your complete knowledge base:',
    renderedCorpus,                      // 全部观察数据（Markdown 格式）
    'Acknowledge what you\'ve received. Summarize...'
  ].join('\n');

  // 用 Claude Agent SDK 启动一个受限 AI 会话
  const queryResult = query({
    prompt: primePrompt,
    options: {
      model: this.getModelId(),
      cwd: OBSERVER_SESSIONS_DIR,
      disallowedTools: KNOWLEDGE_AGENT_DISALLOWED_TOOLS,  // 禁止所有文件/网络操作
      ...
    }
  });

  // 捕获 session_id，存入 corpus.session_id
  for await (const msg of queryResult) {
    if (msg.session_id) sessionId = msg.session_id;
  }
  corpus.session_id = sessionId;
  this.corpusStore.write(corpus);  // 持久化 session_id
}

async query(corpus: CorpusFile, question: string): Promise<QueryResult> {
  // 用 resume: corpus.session_id 恢复已加载知识的 AI 会话
  const queryResult = query({
    prompt: question,
    options: { resume: corpus.session_id!, ... }
  });
  // 如果 session 过期 → 自动 reprime → 重试
}

1
2
3
4
5
6
7
8

const KNOWLEDGE_AGENT_DISALLOWED_TOOLS = [
  'Bash',     // 禁止执行命令（防止知识库里的恶意内容被执行）
  'Read',     // 禁止读文件
  'Write',    // 禁止写文件
  'WebFetch', // 禁止联网
  'Task',     // 禁止生成子 Agent（防止无限嵌套）
  ...
];

1
2
3
4
5
6
7
8

private getFilePath(name: string): string {
  const safeName = this.validateCorpusName(name);  // 只允许 [a-zA-Z0-9._-]
  const resolved = path.resolve(this.corporaDir, `${safeName}.corpus.json`);
  if (!resolved.startsWith(path.resolve(this.corporaDir) + path.sep)) {
    throw new Error('Invalid corpus name');  // 防止 ../../../etc/passwd 类攻击
  }
  return resolved;
}

1
2
3
4

this.db.run('PRAGMA journal_mode = WAL');       // 写时不阻塞读
this.db.run('PRAGMA synchronous = NORMAL');      // 性能与安全的平衡
this.db.run('PRAGMA foreign_keys = ON');         // 级联删除保证一致性
this.db.run('PRAGMA journal_size_limit = 4194304'); // WAL 上限 4MB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

private addObservationHierarchicalFields(): void {
  const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(8);
  if (applied) return;  // 已经执行过，跳过

  const tableInfo = this.db.query('PRAGMA table_info(observations)').all();
  const hasTitle = tableInfo.some(col => col.name === 'title');
  if (hasTitle) {
    // 列存在但没记录版本 → 补记版本号，跳过 DDL
    this.db.prepare('INSERT OR IGNORE INTO schema_versions ...').run(8, ...);
    return;
  }
  // 执行实际迁移...
}

1
2
3
4
5
6
7
8

Layer 1: 表格行（Compact）
  → 大多数历史观察：只有 type/title/time（~20 token/条）

Layer 2: 全文展开（Full）
  → 最近 N 条：包含 narrative 或 facts（~200 token/条）

Layer 3: 摘要（Summary）
  → 最近会话的结构化摘要：request/learned/completed/next_steps

1
2
3
4

CLAUDE_MEM_CONTEXT_OBSERVATIONS = 50    # 总观察数上限
CLAUDE_MEM_CONTEXT_FULL_COUNT = 5       # 展开全文的条数（最近 5 条）
CLAUDE_MEM_CONTEXT_SESSION_COUNT = 3    # 显示最近 N 个会话摘要
CLAUDE_MEM_CONTEXT_FULL_FIELD = 'narrative' | 'facts'  # 展开哪个字段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// ObservationCompiler.ts L288-293
export function getFullObservationIds(observations: Observation[], count: number): Set<number> {
  return new Set(
    observations
      .slice(0, count)       // 只取最近 count 条
      .map(obs => obs.id)
  );
}

// TimelineRenderer.ts L64-70
const shouldShowFull = fullObservationIds.has(obs.id);  // 这条是否在"展开集"里

if (shouldShowFull) {
  const detailField = getDetailField(obs, config);  // narrative 或 facts
  output.push(...Agent.renderAgentFullObservation(obs, timeDisplay, detailField, config));
} else {
  output.push(Agent.renderAgentTableRow(obs, timeDisplay, config));  // 紧凑行
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// TokenCalculator.ts L14-37
export function calculateTokenEconomics(observations: Observation[]): TokenEconomics {
  const totalReadTokens = observations.reduce((sum, obs) => {
    return sum + Math.ceil(
      ((obs.title?.length || 0) + (obs.narrative?.length || 0) + ...) / 4
    );
  }, 0);

  const totalDiscoveryTokens = observations.reduce((sum, obs) => {
    return sum + (obs.discovery_tokens || 0);  // 当初处理时消耗了多少 token
  }, 0);

  const savingsPercent = Math.round((savings / totalDiscoveryTokens) * 100);
  // 通常能节省 80%+ 的 token（处理时消耗 1000 token，注入时只用 200 token）
}

1
2
3
4
5
6
7
8
9

// session-init.ts L89-104
if (semanticInject && prompt.length >= 20) {
  const semanticResult = await executeWithWorkerFallback<SemanticContextResponse>(
    '/api/context/semantic',
    'POST',
    { q: prompt, project, limit },  // 用当前 prompt 做向量搜索
  );
  // 找到语义相关的历史观察，额外注入
}

1
2
3
4
5
6

开源部分（本仓库）                    闭源 Pro（外部）
─────────────────────                ─────────────────
Worker HTTP API（本地端口）      ←──  Memory Stream（Pro UI）连接同一组 API
viewer.html（开源 React UI）     ←──  Pro UI 做同样的事，但功能更多
SQLite + Chroma 数据层           ←──  Pro 只读，不修改数据格式
Settings JSON（含 license key）  ←──  Pro 写 license_key 到 settings

1
2
3
4
5
6
7
8

// ViewerRoutes.ts L12-25
const VIEWER_HTML_CANDIDATE_PATHS: readonly string[] = [
  path.join(packageRoot, 'ui', 'viewer.html'),
  path.join(packageRoot, 'plugin', 'ui', 'viewer.html'),
];

const viewerHtmlBytes: Buffer | null =
  VIEWER_HTML_CANDIDATE_PATHS.find(existsSync) ?? null;

1
2
3
4
5
6

// DataRoutes.ts L93-106
app.get('/api/observations', this.handleGetObservations.bind(this));
app.get('/api/summaries', this.handleGetSummaries.bind(this));
app.get('/api/prompts', this.handleGetPrompts.bind(this));
app.get('/api/projects', this.handleGetProjects.bind(this));
// 没有任何 auth middleware

1
2
3

// SettingsDefaultsManager.ts（settings 字段）
// 没有 CLAUDE_MEM_PRO_LICENSE 等字段
// Pro 功能通过 settings.json 扩展字段来添加，不修改 core defaults

1
2

// ViewerRoutes.ts L53
app.get('/stream', this.handleSSEStream.bind(this));