fluffy-context 0.8.0 → 1.0.0-beta.1

package/ROADMAP-1.0.md

@@ -0,0 +1,70 @@
+# fluffy-context 1.0：可用的项目认知层
+
+状态：第一阶段实现及三批实际使用驱动的迭代，发布候选版本 1.0.0-beta.1，稳定通道仍为 0.8.0。基线：0.8.0。目标不是保存更多对话，而是让不同 agent 在适当时刻取得可信项目知识，并留下可被下次工作验证和复用的结果。
+
+## 产品约束
+
+日常入口收敛到 init、inject、checkpoint、import、report。旧命令保留为诊断与治理接口，不再出现在首次使用必做步骤中。自动注入和知识验证分开：允许自动检索，不允许把出现过的文字自动升级为真。
+
+核心协议独立于 agent：任务请求 → 有预算的证据包 → 按需展开 → 验证结果 → 项目知识。宿主适配器只负责触发和交付。AGENTS.md 是无 hook 宿主的兼容回退，不能声称保证 agent 会调用。默认语义采集；文件活动只能作为弱信号，不能替代证据。
+
+## 六个问题的交付拆分
+
+| 问题 | 第一阶段已实现 | 1.0 正式发布前仍需完成 |
+| --- | --- | --- |
+| 初始化繁琐 | init 编排布局、首次迁移、验证、项目指引、运行时启动；保留已有禁用策略；无后台模式 | 部分迁移中断恢复、跨平台安装矩阵、配置撤销与健康摘要 |
+| 日志快速增长 | 实体增量同步、分段 gzip 重放、观察准入预算与拒绝计数、日志/产物噪声过滤 | 遥测聚合、增量读取索引与长期增长基准 |
+| agent 不主动使用 | 项目级明确触发指引、Claude 项目自动安装、MCP 工具描述给出触发时机、统一 API | 各宿主真实接入测试、触发覆盖率、工具选择实验；不能用 memory 提醒次数冒充接入成功 |
+| 智能注入缺失 | inject 自动推断场景、默认关闭活动噪声、沿用来源/适用性/可信状态过滤、预算和按需展开；Claude hook 接入 | 会话内去重与增量注入、任务切换失效、冲突/新鲜度评分、多语言排序评估、真实 tokenizer |
+| 收益不可量化 | 输入+输出成本、无 telemetry 时收益不可用、移除虚假回本日期、日志构成和现有显式复用指标 | 同任务对照实验、任务结果/测试成功率、避免重复探索的证据、provider token 接入、成本配对和置信区间 |
+| 外部记忆无法吸收 | import 的只读预览与显式 apply，项目范围扫描、字节/条目预算、内容去重、文件行号来源、候选隔离；CLI/MCP/API | 多段结构与 front matter 解析、冲突聚类、变更追踪和撤销、额外来源适配器 |
+
+## 数据品质与演化
+
+候选最少具有 statement、scope、来源和内容指纹。验证时应关联真实代码或测试；失败方案应包含可复现的失败原因。原始记录数量、候选数量和被检索次数都不是知识价值。知识价值以证据有效性、适用范围、实际采用与任务结果来评价。
+
+当前导入器采用保守的文本行抽取（20–1500 字符），每次最多 500 个候选、2000 个扫描条目、8 层目录、单文件 64 KiB、总正文 2 MiB。跳过代码围栏、标题、生成指引块、敏感内容行和符号链接，遵守 .contextignored。正则过滤不保证发现所有秘密；下一阶段需专用脱敏器。未知格式不猜测解析。重复候选不重新激活已拒绝知识。
+
+日志是追加式权威历史，不能直接删旧事件来控制体积。现已支持保留全部事件字节、哈希与顺序的分段 gzip 归档，不依赖丢弃历史的投影快照。归档先验证链、发布临时压缩文件、解压比对，再移除原始段；双副本中断恢复与不一致拒绝已有测试。retentionMaxBytes 现在是可选观察事件的准入预算，不阻止语义事实写入，也不能宣传为全部历史的硬上限。遥测聚合和更快的增量读取仍待后续实现。
+
+本地发布流程已落地：`npm run install:local` 从 tgz 安装，逐文件哈希核验后生成回执，恢复本项目 runtime。用户已授权每批完成后执行该流程，开发过程中优先使用全局 ctx。压缩日志需要新版读取器，旧的常驻 MCP 连接需重启后使用。
+
+## 注入协议与触发
+
+1. 会话开始/上下文恢复：恢复当前任务及已验证约束。
+2. 用户提出新任务：按任务词、文件范围、分支、场景生成证据包。
+3. 新错误出现：查询匹配的已验证死路与证据，按需展开。
+4. 阶段结束：保存完成、待办、决策及验证情况；提取候选供后续验证。
+
+1.0 第一阶段的场景推断是确定性关键词规则，不是模型意图理解。正文预算不包含协议包装。没有宿主事件的 agent 仍需遵循项目指引或主动调用工具；不宣称跨所有 agent 的零配置自动化。核心工具必须 fail open，初始化失败则明确报错且保留原始数据。
+
+Claude Hook 同时修复输出契约：按照 [Claude 官方 Hook 文档](https://code.claude.com/docs/en/hooks)，使用 `hookSpecificOutput.hookEventName` 和 `hookSpecificOutput.additionalContext`，不能把 additionalContext 放在顶层。回归测试覆盖两个事件名及注入字段；真实宿主中的接受与触发仍需接入验收。
+
+运行时还修复关闭竞争：关闭时排空文件观察队列可能再次触发 touch 并重建 5 分钟闲置定时器，导致“已停止”的进程继续存活。关闭开始后不再接受活跃度刷新，并用子进程退出时限测试覆盖该行为。
+
+## 评价体系与发布门槛
+
+建立固定任务集：恢复旧任务、重复错误、跨文件修改、分支切换、矛盾知识、空项目。每个任务对照关闭/开启认知层，在相同仓库基线和验收测试下比较。
+
+- 正确性优先：开启认知层不能降低测试通过率，未验证知识和失效适用范围不得进入可信知识区。
+- 成本：分别记录模型实际输入/输出、工具返回、注入正文、写入与维护成本；不能将 JSON 字符估算当成账单。
+- 收益：报告同任务 paired delta、检索精确率、引用采用率、错误建议率、重复探索次数和完成时间；缺数据标 unavailable。
+- 存储：无变化同步新增事件为零；仅变化一个实体时新增一个语义事件；连续运行的增长曲线和重放耗时可复核。
+- 初始化：新项目、0.8 项目、重复 init、禁用项目、损坏数据、路径空格/中文、Windows/macOS/Linux；原始数据不可被覆盖修复。
+- 导入：dry run 零写入、重复 apply 零新增、路径与隐私边界、条目预算、并发 apply、候选不自动验证。
+
+上述门槛适用于 1.0 正式版。第一阶段通过独立 beta 通道交付，不变更 latest，不代表 1.0 全部完成。
+
+## 后续执行顺序
+
+1. **M2 数据品质与存储**：已完成真实日志基线、分段归档、进程中断恢复、容量准入和有界知识诊断；下一步实现遥测聚合与增量读取索引。完善导入的多段解析、冲突分组与变更追踪，避免用垃圾候选填满知识库。
+2. **M3 会话注入与宿主接入**：定义宿主 capability 声明和 session/task 身份；以内容哈希控制重复注入，任务/分支/知识状态改变时失效；测试 Claude 真实 Hook、通用 MCP 和无 Hook 的项目指引回退。优先做可测的触发可靠性，不先引入 embedding 或常驻 LLM。
+3. **M4 效果实验与发布**：固定任务/模型/仓库基线，收集 provider usage 和测试结果；paired report 展示收益及样本数。完成跨平台 init、迁移、导入、退出和故障恢复，再发布 1.0。
+
+2026-10-09 对本仓库的只读诊断基线：最近 30 天 42 条事件中 35 条为 workspace.paths.changed，已验证 Knowledge、Deadend 和显式复用均为 0；journal 共 1,011,281 字节。这是当时的运行快照，不是产品基准分数；后续 checkpoint 和开发会使数据改变。它说明需要优先建立语义沉淀和验证闭环。
+
+## 本地真实验收记录
+
+- 接入修复批：40 项测试通过，从 tarball 安装并逐文件核验 106 个文件；真实 init 发现并修复旧源码路径被误判为 MCP 冲突的问题；默认 inject 去除重复 provenance 包装。
+- 存储治理批：114 项完整回归通过，dev.1 全局产物逐文件核验 110 个文件。真实首段从 1,050,216 字节压缩到 189,044 字节，解压后与升级前备份逐字节一致；全链 749 条事件校验通过。结果与安装回执在 `.context/builds/`，未将测试夹具写入真实项目。
+- 检索品质批：真实 `knowledge discover --limit 1 --max-chars 450` 暴露全库成对诊断膨胀，并将不符合查询治理条件的记录带出。dev.2 让诊断使用同样过滤、保守冲突规则、候选扫描上限和正文预算，默认查询不泄漏候选或无关记录。

package/dist/src/agent/index.d.ts

@@ -1,4 +1,7 @@
 export * from './api.js';
+export { injectContext } from '../compiler/inject.js';
+export { importMemory } from '../cognition/import-memory.js';
+export { setupProject } from '../runtime/setup.js';
 export type { MaterializeRecipeInput, TransitionRecipeInput, } from '../cognition/recipes.js';
 export type { MaterializeSkillInput, RecordSkillInvocationInput, RecordSkillOutcomeInput, TransitionSkillInput, } from '../cognition/skills.js';
 export type { AcceptEvolutionCandidateInput, ProposeEvolutionInput, ProposeEvolutionResult, TransitionEvolutionProposalInput, } from '../cognition/evolution.js';

package/dist/src/agent/index.js

@@ -1,4 +1,7 @@
 export * from './api.js';
+export { injectContext } from '../compiler/inject.js';
+export { importMemory } from '../cognition/import-memory.js';
+export { setupProject } from '../runtime/setup.js';
 export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';

package/dist/src/capture/context-filter.js

@@ -10,6 +10,8 @@ const builtinPatterns = [
     'coverage/**',
     'tmp/**',
     '.cache/**',
+    '*.log',
+    '*.tgz',
     '.env',
     '.env.*',
     '*.pem',

package/dist/src/cli/main.js

@@ -4,7 +4,7 @@ import { contextCompile, contextExpand, contextOrient, contextUsageReport, inspe
 import { formatUsageReport } from '../cognition/usage-report.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
-import { verifyJournal } from '../cognition/journal.js';
+import { compactJournal, verifyJournal } from '../cognition/journal.js';
 import { projectEvents } from '../cognition/projections.js';
 import { disableRuntime, enableRuntime, ensureRuntimeForSession, runtimeStatus, serveRuntime, setFilesystemEvents, startRuntime, stopRuntime } from '../cognition/runtime.js';
 import { loadRuntimePolicy } from '../cognition/policy.js';
@@ -13,7 +13,9 @@ import { runClaudeCodeHook } from '../hooks/claude-code.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
 import { inspectClaudeIntegration, installClaudeIntegration } from '../integrations/claude-code.js';
 import { doctor, status } from '../runtime/diagnostics.js';
-import { initProject } from '../runtime/init.js';
+import { setupProject } from '../runtime/setup.js';
+import { importMemory } from '../cognition/import-memory.js';
+import { injectContext } from '../compiler/inject.js';
 import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend, transitionKnowledge, transitionDeadend } from '../runtime/knowledge.js';
 import { addNote, listActivity, listNotes } from '../runtime/notes.js';
 import { VERSION } from '../version.js';
@@ -85,12 +87,24 @@ function graphHopsOption(args) {
 const recipeBudgets = (value) => value === undefined ? undefined : Object.fromEntries(value.split(',').map((item) => { const [section, budget] = item.split('=', 2); const parsed = Number(budget); if (!section || !Number.isSafeInteger(parsed) || parsed < 0 || parsed > 100_000)
     throw new Error('--budgets must be section=non-negative-integer up to 100000'); return [section, parsed]; }));
 const HELP = {
-    init: `usage: ctx init [path] [--path <path>]
+    init: `usage: ctx init [path] [--path <path>] [--no-start] [--no-integrations]
 
-Initialize the local .context runtime layout. Re-running init is safe.
+Initialize, migrate, verify, install project guidance and start the runtime. Re-running init preserves policy.
 
 Options:
-  --path <path>  Project path`,
+  --path <path>  Project path
+  --no-start    Configure without starting a background process
+  --no-integrations  Skip project guidance and host configuration`,
+    import: `usage: ctx import [--path <path>] [--apply]
+
+Preview project memory, .claude, .zcode, .cursor, .curcor, .codex and AGENTS.md.
+--apply imports deduplicated, source-linked candidates; verification remains explicit.`,
+    inject: `usage: ctx inject [query] [--path <path>] [--max-chars <number>] [--paths <paths>] [--explain]
+
+Select bounded task context; --explain includes detailed source provenance.`,
+    report: `usage: ctx report [options]
+
+Alias of ctx usage report; supports its window, format and baseline options.`,
     usage: `usage: ctx usage report [options]
 
 Show read-only context asset, reuse, token investment, and operation metrics.
@@ -307,12 +321,16 @@ Record an idempotent use signal that affects deterministic rank only.`,
        ctx skill supersede <skill-id> --rationale <text> --supersedes <entity:id> [--path <path>]
        ctx skill invoke <skill-id> --invocation-id <id> --caller-event <id> --input-hash <hash> [--path <path>]
        ctx skill outcome <skill-id> --invocation-id <id> --outcome-id <id> --caller-event <id> --outcome <value> --summary <text> [--path <path>]`,
-    journal: `usage: ctx journal verify [--path <path>]
+    journal: `usage: ctx journal verify|compact [--path <path>] [--apply]
 
 Validate the v2 journal hash chain and replay projections in memory.`,
     'journal verify': `usage: ctx journal verify [--path <path>]
 
 Validate journal integrity without writing derived state.`,
+    'journal compact': `usage: ctx journal compact [--path <path>] [--apply]
+
+Preview or apply lossless gzip archival. Replays the full hash chain before and after.
+Archived projects require this development version or newer readers.`,
     deadends: `usage: ctx deadends [--all] [--path <path>]
 
 List recorded deadends.`,
@@ -454,7 +472,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|skill|recipe|evolution|journal [options]
+    return `usage: ctx init|inject|import|report|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|skill|recipe|evolution|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -479,7 +497,7 @@ function printHelp(args) {
         || (command === 'knowledge' && ['verify', 'discover', 'deprecate', 'reject'].includes(args[1]))
         || (command === 'deadend' && ['verify', 'obsolete', 'reject'].includes(args[1]))
         || (command === 'feedback' && args[1] === 'use')
-        || (command === 'journal' && args[1] === 'verify')
+        || (command === 'journal' && ['verify', 'compact'].includes(args[1]))
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
         || (command === 'recipe' && ['list', 'inspect', 'materialize', 'verify', 'publish', 'deprecate', 'supersede'].includes(args[1]))
@@ -502,6 +520,8 @@ function validatePositionals(values, max, usageText) {
         throw new Error(usageText);
 }
 async function run(args) {
+    if (args[0] === 'report' && !args.includes('--help'))
+        args = ['usage', 'report', ...args.slice(1)];
     if (args.includes('--version')) {
         print(VERSION);
         return;
@@ -516,10 +536,24 @@ async function run(args) {
     const target = option(args, '--path');
     switch (command) {
         case 'init': {
-            validateOptions(args.slice(1), ['--path'], ['--path']);
+            validateOptions(args.slice(1), ['--path', '--no-start', '--no-integrations'], ['--path']);
             const values = positionals(args.slice(1), ['--path']);
             validatePositionals(values, 1, HELP.init);
-            print(await initProject(target ?? values[0]));
+            print(await setupProject(target ?? values[0], { start: !args.includes('--no-start'), integrations: !args.includes('--no-integrations') }));
+            return;
+        }
+        case 'import': {
+            validateOptions(args.slice(1), ['--path', '--apply'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.import);
+            print(await importMemory(target, args.includes('--apply')));
+            return;
+        }
+        case 'inject': {
+            const valueOptions = ['--path', '--max-chars', '--paths'];
+            validateOptions(args.slice(1), [...valueOptions, '--explain'], valueOptions);
+            const values = positionals(args.slice(1), valueOptions);
+            validatePositionals(values, 1, HELP.inject);
+            print(await injectContext(target, { query: values[0], paths: listOption(args, '--paths'), maxChars: numericOption(args, '--max-chars', 2400), explain: args.includes('--explain') }, 'cli'));
             return;
         }
         case 'checkpoint': {
@@ -917,6 +951,12 @@ async function run(args) {
             throw new Error(HELP.recipe);
         }
         case 'journal': {
+            if (args[1] === 'compact') {
+                validateOptions(args.slice(2), ['--path', '--apply'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['journal compact']);
+                print(await compactJournal(target, { apply: args.includes('--apply') }));
+                return;
+            }
             if (args[1] !== 'verify')
                 throw new Error(HELP.journal);
             validateOptions(args.slice(2), ['--path'], ['--path']);

package/dist/src/cognition/admission.d.ts

@@ -0,0 +1,8 @@
+interface AdmissionStats {
+    schemaVersion: 1;
+    dropped: Record<string, number>;
+    updatedAt: string;
+}
+export declare function readAdmissionStats(root: string): Promise<AdmissionStats>;
+export declare function recordAdmissionDrop(root: string, type: string): Promise<void>;
+export {};

package/dist/src/cognition/admission.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { cognitionRuntimeDirectory } from '../storage/layout.js';
+import { readJson, isRecord } from '../storage/json-store.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+const statsPath = (root) => path.join(cognitionRuntimeDirectory(root), 'admission.json');
+export async function readAdmissionStats(root) {
+    try {
+        return await readJson(statsPath(root), (value) => isRecord(value)
+            && value.schemaVersion === 1 && typeof value.updatedAt === 'string' && isRecord(value.dropped)
+            && Object.values(value.dropped).every((count) => typeof count === 'number' && Number.isSafeInteger(count) && count >= 0));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { schemaVersion: 1, dropped: {}, updatedAt: '' };
+        throw error;
+    }
+}
+// The journal writer lock serializes these counters too. Never store content.
+export async function recordAdmissionDrop(root, type) {
+    const stats = await readAdmissionStats(root);
+    stats.dropped[type] = Math.min(Number.MAX_SAFE_INTEGER, (stats.dropped[type] ?? 0) + 1);
+    stats.updatedAt = new Date().toISOString();
+    await atomicWriteJson(statsPath(root), stats);
+}

package/dist/src/cognition/import-memory.d.ts

@@ -0,0 +1,18 @@
+export declare function importMemory(startPath?: string, apply?: boolean): Promise<{
+    projectRoot: string;
+    applied: boolean;
+    scannedBytes: number;
+    results: {
+        status: string;
+        knowledgeId: string | null;
+        source: string;
+        line: number;
+        statement: string;
+        fingerprint: string;
+    }[];
+    skipped: {
+        source: string;
+        reason: string;
+    }[];
+    trust: string;
+}>;

package/dist/src/cognition/import-memory.js

@@ -0,0 +1,124 @@
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { filterPaths } from '../capture/context-filter.js';
+import { learnKnowledge, listKnowledge } from '../runtime/knowledge.js';
+import { loadManifest } from '../runtime/init.js';
+import { withLock } from '../storage/lock.js';
+import { locksDirectory } from '../storage/layout.js';
+const sources = ['memory', '.memory', '.claude', '.zcode', '.cursor', '.curcor', '.codex', 'AGENTS.md', 'agents.md', 'CLAUDE.md', 'MEMORY.md', '.cursorrules'];
+const hash = (text) => crypto.createHash('sha256').update(text).digest('hex');
+const sensitive = /(?:api[_-]?key|token|password|secret)\s*[:=]\s*\S+|\b(?:sk-|sk_|ghp_|github_pat_)[A-Za-z0-9_-]+|-----BEGIN .*PRIVATE KEY-----/i;
+export async function importMemory(startPath, apply = false) {
+    const root = await resolveProjectRoot(startPath);
+    await loadManifest(root);
+    const candidates = [];
+    const skipped = [];
+    const visited = new Set();
+    let bytes = 0;
+    let entries = 0;
+    const canonicalRoot = await realpath(root);
+    async function scan(relative, depth = 0) {
+        if (++entries > 2000 || candidates.length >= 500 || depth > 8) {
+            skipped.push({ source: relative, reason: 'scan-budget' });
+            return;
+        }
+        const absolute = path.join(root, relative);
+        let info;
+        try {
+            info = await lstat(absolute);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        if (info.isSymbolicLink()) {
+            skipped.push({ source: relative, reason: 'symlink' });
+            return;
+        }
+        const resolved = await realpath(absolute);
+        const within = path.relative(canonicalRoot, resolved);
+        if (within.startsWith('..') || path.isAbsolute(within)) {
+            skipped.push({ source: relative, reason: 'outside-project' });
+            return;
+        }
+        const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        if ((await filterPaths(root, [relative])).length === 0) {
+            skipped.push({ source: relative, reason: 'ignored' });
+            return;
+        }
+        if (info.isDirectory()) {
+            for (const entry of (await readdir(absolute)).sort()) {
+                if (entries >= 2000 || candidates.length >= 500) {
+                    skipped.push({ source: relative, reason: 'scan-budget' });
+                    break;
+                }
+                await scan(path.join(relative, entry), depth + 1);
+            }
+            return;
+        }
+        if (!info.isFile() || !/\.(?:md|mdc|txt)$/i.test(relative) && path.basename(relative) !== '.cursorrules')
+            return;
+        if (info.size > 64 * 1024 || bytes + info.size > 2 * 1024 * 1024) {
+            skipped.push({ source: relative, reason: 'byte-budget' });
+            return;
+        }
+        bytes += info.size;
+        const text = await readFile(absolute, 'utf8');
+        let managed = false;
+        let code = false;
+        for (const [index, raw] of text.split(/\r?\n/).entries()) {
+            if (raw.includes('<!-- fluffy-context:start -->')) {
+                managed = true;
+                continue;
+            }
+            if (raw.includes('<!-- fluffy-context:end -->')) {
+                managed = false;
+                continue;
+            }
+            if (managed)
+                continue;
+            if (/^\s*```/.test(raw)) {
+                code = !code;
+                continue;
+            }
+            if (code || /^\s*#/.test(raw))
+                continue;
+            const statement = raw.replace(/^\s*(?:[-*+] |\d+\. )/, '').trim();
+            if (statement.length < 20 || statement.length > 1500)
+                continue;
+            if (sensitive.test(statement)) {
+                skipped.push({ source: `${relative}:${index + 1}`, reason: 'potential-secret' });
+                continue;
+            }
+            if (candidates.length >= 500) {
+                skipped.push({ source: relative, reason: 'candidate-budget' });
+                break;
+            }
+            candidates.push({ source: relative.replaceAll('\\', '/'), line: index + 1, statement,
+                fingerprint: hash(statement.replace(/\s+/g, ' ').toLowerCase()) });
+        }
+    }
+    for (const source of sources)
+        await scan(source);
+    const run = async () => {
+        const known = new Set((await listKnowledge(root, true)).map((item) => hash(item.statement.replace(/\s+/g, ' ').toLowerCase())));
+        const results = [];
+        for (const candidate of candidates) {
+            const duplicate = known.has(candidate.fingerprint);
+            known.add(candidate.fingerprint);
+            const record = apply && !duplicate ? await learnKnowledge(root, candidate.statement, {
+                kind: 'imported-memory', evidence: [`${candidate.source}:${candidate.line}`, `sha256:${candidate.fingerprint}`],
+            }) : null;
+            results.push({ ...candidate, status: duplicate ? 'duplicate' : apply ? 'candidate' : 'preview', knowledgeId: record?.knowledgeId ?? null });
+        }
+        return { projectRoot: root, applied: apply, scannedBytes: bytes, results, skipped,
+            trust: 'Imported text is unverified evidence; inspect and verify against the project before injection.' };
+    };
+    return apply ? withLock(path.join(locksDirectory(root), 'memory-import.lock'), run) : run();
+}

package/dist/src/cognition/journal-segments.d.ts

@@ -0,0 +1,11 @@
+export declare const JOURNAL_SEGMENT_BYTES: number;
+export declare function journalFiles(root: string): Promise<string[]>;
+export declare function readSegment(root: string, name: string): Promise<Buffer>;
+export declare function archiveSegment(root: string, name: string): Promise<void>;
+export declare function appendJournalLine(root: string, line: string): Promise<void>;
+export declare function journalStorage(root: string, expand?: boolean): Promise<{
+    bytes: number;
+    expandedBytes: number | null;
+    archives: number;
+    segments: number;
+}>;

package/dist/src/cognition/journal-segments.js

@@ -0,0 +1,129 @@
+import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gzip, gunzip } from 'node:zlib';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { cognitionJournalDirectory } from '../storage/layout.js';
+const compress = promisify(gzip);
+const decompress = promisify(gunzip);
+export const JOURNAL_SEGMENT_BYTES = 1024 * 1024;
+export async function journalFiles(root) {
+    let files;
+    try {
+        files = await readdir(cognitionJournalDirectory(root));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const segments = new Map();
+    for (const file of files) {
+        if (!file.endsWith('.ndjson') && !file.endsWith('.ndjson.gz'))
+            continue;
+        if (!/^\d{8}\.ndjson(?:\.gz)?$/.test(file))
+            throw new Error(`unrecognized journal segment: ${file}`);
+        const base = file.replace(/\.gz$/, '');
+        if (!segments.has(base) || file.endsWith('.gz'))
+            segments.set(base, file);
+    }
+    return [...segments.values()].sort();
+}
+async function optional(file) {
+    try {
+        return await readFile(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function readSegment(root, name) {
+    const file = path.join(cognitionJournalDirectory(root), name);
+    if (!name.endsWith('.gz')) {
+        const raw = await optional(file);
+        // An unlocked reader may race a successful archive publication.
+        return raw ?? readSegment(root, `${name}.gz`);
+    }
+    let decoded;
+    try {
+        decoded = await decompress(await readFile(file));
+    }
+    catch (error) {
+        throw new Error(`invalid journal archive ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const raw = await optional(file.slice(0, -3));
+    if (raw && !raw.equals(decoded))
+        throw new Error(`journal archive/raw mismatch: ${name}`);
+    return decoded;
+}
+// Caller holds cognition-journal.lock. Publish and validate before removing raw
+// bytes; a crash with both representations is safe and validated on every read.
+export async function archiveSegment(root, name) {
+    if (name.endsWith('.gz')) {
+        await readSegment(root, name);
+        await rm(path.join(cognitionJournalDirectory(root), name.slice(0, -3)), { force: true });
+        return;
+    }
+    const source = path.join(cognitionJournalDirectory(root), name);
+    const raw = await readFile(source);
+    if (!raw.length)
+        return;
+    if (raw.at(-1) !== 10)
+        throw new Error(`cannot archive incomplete journal segment: ${name}`);
+    const target = `${source}.gz`;
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, await compress(raw, { level: 9 }), { flag: 'wx' });
+        await rename(temporary, target);
+        if (!(await readSegment(root, `${name}.gz`)).equals(raw))
+            throw new Error(`archive verification failed: ${name}`);
+        await rm(source);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function appendJournalLine(root, line) {
+    const directory = cognitionJournalDirectory(root);
+    await mkdir(directory, { recursive: true });
+    const latest = (await journalFiles(root)).at(-1);
+    let number = latest ? Number(latest.slice(0, 8)) : 1;
+    if (latest?.endsWith('.gz'))
+        number += 1;
+    else if (latest && (await stat(path.join(directory, latest))).size >= JOURNAL_SEGMENT_BYTES) {
+        await archiveSegment(root, latest);
+        number += 1;
+    }
+    if (number > 99_999_999)
+        throw new Error('journal segment limit exceeded');
+    await appendFile(path.join(directory, `${String(number).padStart(8, '0')}.ndjson`), line, 'utf8');
+}
+export async function journalStorage(root, expand = false) {
+    const files = await journalFiles(root);
+    let bytes = 0;
+    let expandedBytes = expand ? 0 : null;
+    let archives = 0;
+    for (const file of files) {
+        let metadata;
+        try {
+            metadata = await stat(path.join(cognitionJournalDirectory(root), file));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && !file.endsWith('.gz')) {
+                metadata = await stat(path.join(cognitionJournalDirectory(root), `${file}.gz`));
+            }
+            else
+                throw error;
+        }
+        bytes += metadata.size;
+        if (file.endsWith('.gz')) {
+            archives += 1;
+            bytes += (await optional(path.join(cognitionJournalDirectory(root), file.slice(0, -3))))?.length ?? 0;
+        }
+        if (expandedBytes !== null)
+            expandedBytes += (await readSegment(root, file)).length;
+    }
+    return { bytes, expandedBytes, archives, segments: files.length };
+}

package/dist/src/cognition/journal.d.ts

@@ -21,6 +21,19 @@ export declare function readJournal(startPath?: string, options?: {
     allowPartialTail?: boolean;
 }): Promise<CognitionEvent[]>;
 export declare function verifyJournal(startPath?: string): Promise<CognitionEvent[]>;
+export declare function compactJournal(startPath?: string, options?: {
+    apply?: boolean;
+    minBytes?: number;
+}): Promise<{
+    applied: boolean;
+    eligible: string[];
+    events: number;
+    headHash: string | null;
+    bytesBefore: number;
+    bytesAfter: number;
+    savedBytes: number;
+    archives: number;
+}>;
 export declare function appendEvent<T>(startPath: string | undefined, input: AppendEventInput<T>): Promise<{
     event: CognitionEvent<T>;
     appended: boolean;