rawmem

rawmem

English | 简体中文

rawmem 是一个轻量、本地优先的证据台账，用于 AI 和人工工作流。

这个想法刻意保持简单：

现在存储，日后理解。

AI 记忆系统通常从总结开始。rawmem 则从更底层开始： 只追加原始证据。一轮对话、2px 的 UI 微调、一个 Bug 修复、一次命令运行、 一份 git 快照、一段浏览器剪辑，或一次编码 Agent 完成的任务，都可以成为 同一种本地事件。

边界很简单：采集不等于回忆。台账是一个源层。之后可以基于它进行 审阅、筛选、MemoryDSL 转换、偏好挖掘和项目规则提取。

为什么要创建它

单独来看，小事实显得杂乱。但在不同时间和项目中反复出现时，它们就会形成模式：

• “这个图标太小了；放大 2px。”
• “AI 又忘了更新桌面软件包。”
• “这个项目倾向于使用只追加的 Bug 记录。”
• “同一类边界 Bug 在三个代码仓库中都出现了。”

磁盘空间很便宜。丢失历史的代价很高。

安装

刚开始编程？请选择 Windows 应用（EXE）。 EXE 是一个 Windows 程序，双击即可打开。运行它无需安装 Python，也无需使用终端命令。

适用对象	选择	要求
想使用图形应用的 Windows 用户	Windows EXE 预览版	已构建的 rawmem.exe；无需 Python
想使用命令或集成的开发者	Python CLI	Python 3.10+ 和 Git，用于执行下方的源码安装

选择一种方式即可；不需要两种都选。**目前尚未提供新版 EXE 预览版的可下载版本。**开发者必须先从源码构建。 不熟悉编程的用户可以等待 EXE 发布版，而不必执行下方的 Python 命令。

Windows 应用（EXE 预览版）

获取已构建的 rawmem.exe 后，双击打开，选择存储文件夹， 决定是否在登录时启动，然后点击开始录制。保存浏览器内容 需要使用可选扩展。请参阅 Windows recorder 了解设置和构建说明。此预览版未经签名，扩展仍需通过开发者模式手动安装。

Python CLI（适用于开发者）

EXE 用户可以跳过本节。安装 Python 3.10+ 和 Git 后，在 PowerShell 中运行以下 命令：

git clone https://github.com/Liyuan1992/rawmem.git
cd rawmem
python -m pip install --user -e .

核心运行时没有第三方依赖。DeepSeek Harness 压缩会话采集 和 MCP 服务是可选的额外功能：

python -m pip install --user -e ".[deepseek-harness,mcp]"

如需安装已发布的 v0.7.1 wheel，而不克隆代码仓库：

python -m pip install "rawmem[deepseek-harness,mcp] @ https://github.com/Liyuan1992/rawmem/releases/download/v0.7.1/rawmem-0.7.1-py3-none-any.whl"

请确保用户 Scripts 目录（例如 %APPDATA%\Python\Python312\Scripts）已添加到 PATH，这样就能在任意目录中使用 rawmem。

一次性设置

rawmem setup --global --install-startup --dry-run  # inspect first; writes nothing
rawmem setup --global --yes           # global config + git hooks for all repos
rawmem setup --install-startup --yes  # run the daemon headless at every logon
rawmem setup --start-daemon           # start it right now
rawmem config --show-browser-token    # paste into the browser extension options
rawmem doctor                         # verify the complete installation

完成后，守护进程会被动跟踪 Claude Code、Codex 和 Cursor 会话， 跟踪 PowerShell 历史记录，监视已配置的目录，并提供 浏览器采集端点——无需你对每个事件进行任何操作。剪贴板轮询可用，但默认禁用；可在配置中明确启用， 或使用 rawmem config --include-clipboard 启用。 指导原则是 被动采集优于主动报告：证据取自其他工具已经写入的日志，而不是要求 Agent 记得 主动报告。

完整的设置选项和浏览器扩展说明，请参阅 docs/SETUP.md。

如需使用 DeepSeek Harness 采集并通过 MCP 进行有界的只读访问，请参阅 docs/DEEPSEEK_HARNESS.md。

命令

后台捕获（主要方式）：

rawmem daemon              # run all background surfaces in one process
rawmem daemon --status     # task counters, errors, last run times
rawmem doctor              # config, storage, daemon, token, startup, hooks, events
rawmem doctor --strict     # warnings also produce a nonzero exit code
rawmem sync                # one manual tailer pass
rawmem sync --backfill     # first run: also ingest existing history
rawmem config --disable-clipboard
rawmem config --rotate-browser-token

预览或移除集成：

rawmem setup --global --install-startup --dry-run
rawmem uninstall --dry-run
rawmem uninstall                    # disables integrations; keeps ~/.rawmem
rawmem uninstall --remove-home --yes  # also deletes the ledger and local state

检查账本：

rawmem tail --limit 10
rawmem tail --source claude-code --limit 5
rawmem tail --project rawmem --type agent_user_turn --json
rawmem verify --json
rawmem export --cursor-file .rawmem\consumer-cursor.json --limit 100
rawmem seal --yes --json            # unchanged read-only archive + linked active ledger
rawmem archives --json              # metadata-only derived archive registry
rawmem export --archive .rawmem\archives\old.jsonl  # explicit; metadata-only default

rawmem export 使用稳定的 rawmem.cursor.v1 契约，且无需加载整个账本。游标绑定到账本标识、字节偏移量和边界哈希，因此会明确报告截断、替换或轮转，而不会悄悄跳过或重复证据。请参阅 docs/LEDGER_PROTOCOL.md。

rawmem verify 严格只读：不会创建或刷新锁定／状态辅助文件。rawmem seal 会保留历史字节不变，记录完整的验证报告和每一项已接受的 previous_hash_mismatch，在 Windows 上将旧账本标记为 ReadOnly，并在相同的配置路径创建链完整的活动账本。读取归档需要 --archive；返回结果前会对完整归档进行哈希处理，默认仅提供不含正文的元数据投影，并显示记录的完整性警告。

手动和脚本化捕获：

rawmem capture --source manual --type note --text "First rawmem event"
"The button should be 2px larger." | rawmem capture --source clipboard --type ui_feedback --stdin
rawmem ingest --file event.json
"Selected page text" | rawmem clip --stdin --url "https://example.com"
rawmem run --source terminal -- python --version
rawmem git-snapshot

当前覆盖范围

捕获会完整保留受支持的文本，不设字符数上限，即使旧配置中仍包含 max_chars 也一样。来源批次大小是处理预算，不会拆分完整记录。浏览器捕获仅在明确点击时保存已加载的文档；不会获取隐藏历史记录。

界面	方式	写入账本的内容
Claude Code 会话	守护进程跟踪器（零配置）	用户／助手轮次、项目、会话、分支
Codex 会话	守护进程跟踪器（零配置）	用户／助手轮次、项目、会话
Cursor Agent 转录	守护进程跟踪器（零配置）	用户／助手轮次、工作区、会话
DeepSeek Harness 会话	可选的守护进程跟踪器（设置后零配置）	直接的用户／模型轮次；仅工具名称／ID／状态元数据
WorkBuddy 本地历史记录	可选的守护进程跟踪器（桌面设置会启用）	5.1 风格的 JSONL 消息文本和来源标识
OpenClaw 本地历史记录	可选的守护进程跟踪器（桌面设置会启用）	旧版 JSONL 和新版 SQLite 转录消息；共享标识去重
Shell 命令	守护进程跟踪 PSReadLine 历史记录	每条已完成的命令行
剪贴板	守护进程轮询器（去重，可选）	剪贴板文本变更
所有仓库的 Git 生命周期	setup --global --yes 配置的 core.hooksPath 钩子	提交／检出／合并／重写／推送快照
文件变更	守护进程监视器	批量记录创建／修改／删除的路径
浏览器页面	MV3 扩展（extension/）+ 受令牌保护的 localhost 端点	选中文本或页面文本、标题、URL
任意适配器／工具	ingest / POST /capture	JSON 事件负载
手动笔记	capture / clip / run	原始文本、标签、制品、命令结果

存储

默认情况下，事件会写入：

~/.rawmem/events.jsonl

使用 --local 将内容写入当前项目的私有账本：

.rawmem/events.jsonl

使用 --ledger <path> 或 RAWMEM_LEDGER 指定账本路径。

捕获策略在 ~/.rawmem/config.json 的 privacy 下配置。可选的项目／路径允许列表采用默认拒绝策略；常见的机密格式会在追加前进行脱敏；制品默认以元数据引用的形式保存，而非嵌入内容。守护进程状态和 rawmem doctor 会显示来源覆盖范围、跳过的事件、脱敏情况和游标健康状况，但不会打印捕获的文本。

Git 会忽略 .rawmem/，因为原始证据可能包含私人文本、路径、命令输出和本地工作上下文。

事件格式

每行都是 JSON：

{
  "schema": "rawmem.event.v1",
  "event_id": "evt_...",
  "ts": "2026-07-09T00:00:00Z",
  "source": "codex",
  "event_type": "task_note",
  "project": "rawmem",
  "cwd": "/workspace/fictional-rawmem",
  "summary": "User asked for a local-first raw evidence ledger.",
  "raw_text": "User asked for a local-first raw evidence ledger.",
  "tags": [],
  "artifacts": [],
  "payload": {},
  "privacy": {
    "scope": "local_only",
    "review_required": true
  },
  "previous_hash": null,
  "content_hash": "..."
}

previous_hash / content_hash 链是一种轻量级的篡改证据机制。它并非安全边界，但能让意外重写更容易被发现。

适配器策略

rawmem 不应试图通过一个庞大的集成来覆盖所有 AI 工具。稳定的部分是事件账本。采集适配器可以小巧且可选：

• 为 Codex、Claude Code、shell 命令和构建脚本提供 CLI 包装器。
• 为 WorkBuddy、QWork 或自定义脚本等工具提供通用 JSON 导入。
• 为最终会更改代码仓库的工具提供 Git/文件监视器。
• 为 Web AI 聊天、问题页面、文档和网页剪藏提供 localhost 浏览器采集、书签脚本，以及后续的浏览器扩展。
• 为暴露日志、导出功能、插件或 API 的工具提供专用适配器。
• 提供手动热键/剪贴板采集，作为低门槛的备用方案。

所有适配器都应输出相同的事件架构。

MCP 是查询适配器，而不是晋升路径。rawmem-mcp 仅公开不含路径的状态、数量有限的近期事件和归档元数据。默认只提供摘要访问；原始正文需要明确授予 read:full 权限范围。

隐私原则

• 本地优先。
• 默认不上传。
• 不自动晋升记忆。
• 后台采集必须选择启用。
• 默认关闭剪贴板轮询。
• 浏览器采集需要使用在 ~/.rawmem/config.json 中创建的本地令牌。
• 扩展选项页面可以测试守护进程的连接情况和令牌是否被接受。
• 在整台机器上设置 Git 钩子需要使用 --yes。
• 除非明确指定 --remove-home --yes，否则 rawmem uninstall 会保留采集的数据。
• 将原始事件与已审核或衍生的记忆分开存储。
• 浏览器/应用采集优先使用允许列表。

在日常使用的机器上启用后台采集前，请参阅 PRIVACY.md 和 SECURITY.md。

开发

$env:PYTHONPATH = "src"
python -m unittest discover -s tests
python scripts/open_source_audit.py