{
  "markdown": "# rawmem\n\n<!-- mcp-name: io.github.Liyuan1992/rawmem -->\n\n`rawmem` is a tiny local-first evidence ledger for AI and human workflows.\n\nThe idea is deliberately small:\n\n> Store now, understand later.\n\nAI memory systems often start by summarizing. `rawmem` starts one layer lower:\nappend-only raw evidence. A chat turn, a 2px UI tweak, a bug fix, a command run,\na git snapshot, a browser clip, or a coding-agent completion can all become the\nsame kind of local event.\n\nThe hard boundary is simple: capture is not recall. The ledger is a source\nlayer. Review, filtering, MemoryDSL conversion, preference mining, and project\nrules can be derived later.\n\n## Why This Exists\n\nSmall facts look noisy alone. Repeated across time and projects, they become\npatterns:\n\n- \"This icon is too small; make it 2px bigger.\"\n- \"The AI forgot to update the desktop package again.\"\n- \"This project prefers append-only bug records.\"\n- \"The same class of boundary bug appeared in three repos.\"\n\nDisk is cheap. Missing history is expensive.\n\n## Install\n\n```powershell\ngit clone https://github.com/Liyuan1992/rawmem.git\ncd rawmem\npython -m pip install --user -e .\n```\n\nThe core runtime has no third-party dependencies. DeepSeek Harness compressed\nsession capture and the MCP server are optional extras:\n\n```powershell\npython -m pip install --user -e \".[deepseek-harness,mcp]\"\n```\n\nTo install the published `v0.7.1` wheel without cloning the repository:\n\n```powershell\npython -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\"\n```\n\nMake sure the user Scripts\ndirectory (e.g. `%APPDATA%\\Python\\Python312\\Scripts`) is on PATH so `rawmem`\nworks from any directory.\n\n## One-Time Setup\n\n```powershell\nrawmem setup --global --install-startup --dry-run  # inspect first; writes nothing\nrawmem setup --global --yes           # global config + git hooks for all repos\nrawmem setup --install-startup --yes  # run the daemon headless at every logon\nrawmem setup --start-daemon           # start it right now\nrawmem config --show-browser-token    # paste into the browser extension options\nrawmem doctor                         # verify the complete installation\n```\n\nAfter this the daemon passively tails Claude Code, Codex, and Cursor sessions,\ntails PowerShell history, watches configured directories, and serves the\nbrowser-capture endpoint — with zero per-event action from you. Clipboard\npolling is available but disabled by default; enable it explicitly in config\nor with `rawmem config --include-clipboard`.\nThe guiding principle is **passive over self-report**: evidence is pulled\nfrom logs other tools already write, not pushed by agents remembering to\nreport back.\n\nSee [docs/SETUP.md](docs/SETUP.md) for the full setup matrix and the\nbrowser extension.\n\nFor DeepSeek Harness capture plus bounded read-only MCP access, see\n[docs/DEEPSEEK_HARNESS.md](docs/DEEPSEEK_HARNESS.md).\n\n![rawmem DeepSeek Harness demo](docs/assets/deepseek-harness-demo.gif)\n\n## Commands\n\nBackground capture (the primary path):\n\n```powershell\nrawmem daemon              # run all background surfaces in one process\nrawmem daemon --status     # task counters, errors, last run times\nrawmem doctor              # config, storage, daemon, token, startup, hooks, events\nrawmem doctor --strict     # warnings also produce a nonzero exit code\nrawmem sync                # one manual tailer pass\nrawmem sync --backfill     # first run: also ingest existing history\nrawmem config --disable-clipboard\nrawmem config --rotate-browser-token\n```\n\nPreview or remove integrations:\n\n```powershell\nrawmem setup --global --install-startup --dry-run\nrawmem uninstall --dry-run\nrawmem uninstall                    # disables integrations; keeps ~/.rawmem\nrawmem uninstall --remove-home --yes  # also deletes the ledger and local state\n```\n\nInspect the ledger:\n\n```powershell\nrawmem tail --limit 10\nrawmem tail --source claude-code --limit 5\nrawmem tail --project rawmem --type agent_user_turn --json\nrawmem verify --json\nrawmem export --cursor-file .rawmem\\consumer-cursor.json --limit 100\nrawmem seal --yes --json            # unchanged read-only archive + linked active ledger\nrawmem archives --json              # metadata-only derived archive registry\nrawmem export --archive .rawmem\\archives\\old.jsonl  # explicit; metadata-only default\n```\n\n`rawmem export` uses the stable `rawmem.cursor.v1` contract and never needs to\nload the whole ledger. Cursors bind to a ledger identity plus a byte offset and\nboundary hash, so truncation, replacement, or rotation is reported explicitly\ninstead of silently skipping or duplicating evidence. See\n[docs/LEDGER_PROTOCOL.md](docs/LEDGER_PROTOCOL.md).\n\n`rawmem verify` is strictly read-only: it never creates or refreshes lock/state\nsidecars. `rawmem seal` keeps historical bytes unchanged, records the full\nverification report and every accepted `previous_hash_mismatch`, marks the old\nledger ReadOnly on Windows, and creates a chain-complete active ledger at the\nsame configured path. Archive reads require `--archive`; they hash the complete\narchive before returning results, default to a body-free metadata projection,\nand surface recorded integrity warnings.\n\nManual and scripted capture:\n\n```powershell\nrawmem capture --source manual --type note --text \"First rawmem event\"\n\"The button should be 2px larger.\" | rawmem capture --source clipboard --type ui_feedback --stdin\nrawmem ingest --file event.json\n\"Selected page text\" | rawmem clip --stdin --url \"https://example.com\"\nrawmem run --source terminal -- python --version\nrawmem git-snapshot\n```\n\n## Current Coverage\n\n| Surface | How | What lands in the ledger |\n| --- | --- | --- |\n| Claude Code sessions | daemon tailer (zero friction) | user/assistant turns, project, session, branch |\n| Codex sessions | daemon tailer (zero friction) | user/assistant turns, project, session |\n| Cursor agent transcripts | daemon tailer (zero friction) | user/assistant turns, workspace, session |\n| DeepSeek Harness sessions | opt-in daemon tailer (zero friction after setup) | direct user/model turns; tool name/id/status metadata only |\n| Shell commands | daemon tailer of PSReadLine history | every completed command line |\n| Clipboard | daemon poller (deduped, opt-in) | clipboard text changes |\n| Git lifecycle, all repos | `setup --global --yes` core.hooksPath hooks | commit/checkout/merge/rewrite/push snapshots |\n| File changes | daemon watcher | batched created/modified/deleted paths |\n| Browser pages | MV3 extension (`extension/`) + token-protected localhost endpoint | selection or page text, title, URL |\n| Any adapter/tool | `ingest` / POST `/capture` | JSON event payloads |\n| Manual notes | `capture` / `clip` / `run` | raw text, tags, artifacts, command results |\n\n## Storage\n\nBy default, events are written to:\n\n```text\n~/.rawmem/events.jsonl\n```\n\nUse `--local` to write to the current project's private ledger:\n\n```text\n.rawmem/events.jsonl\n```\n\nUse `--ledger <path>` or `RAWMEM_LEDGER` for an explicit ledger path.\n\nCapture policy is configured under `privacy` in `~/.rawmem/config.json`.\nOptional project/path allowlists fail closed, common secret shapes are redacted\nbefore append, and artifacts default to metadata references rather than\nembedded content. Daemon status and `rawmem doctor` expose source coverage,\nskipped events, redactions, and cursor health without printing captured text.\n\n`.rawmem/` is ignored by Git because raw evidence can contain private text,\npaths, command output, and local work context.\n\n## Event Shape\n\nEach line is JSON:\n\n```json\n{\n  \"schema\": \"rawmem.event.v1\",\n  \"event_id\": \"evt_...\",\n  \"ts\": \"2026-07-09T00:00:00Z\",\n  \"source\": \"codex\",\n  \"event_type\": \"task_note\",\n  \"project\": \"rawmem\",\n  \"cwd\": \"/workspace/fictional-rawmem\",\n  \"summary\": \"User asked for a local-first raw evidence ledger.\",\n  \"raw_text\": \"User asked for a local-first raw evidence ledger.\",\n  \"tags\": [],\n  \"artifacts\": [],\n  \"payload\": {},\n  \"privacy\": {\n    \"scope\": \"local_only\",\n    \"review_required\": true\n  },\n  \"previous_hash\": null,\n  \"content_hash\": \"...\"\n}\n```\n\nThe `previous_hash` / `content_hash` chain is a lightweight tamper-evidence\nmechanism. It is not a security boundary, but it makes accidental rewrites more\nvisible.\n\n## Adapter Strategy\n\n`rawmem` should not chase every AI tool with one giant integration. The stable\npiece is the ledger. Capture adapters can be small and optional:\n\n- CLI wrappers for Codex, Claude Code, shell commands, and build scripts.\n- Generic JSON ingest for tools like WorkBuddy, QWork, or custom scripts.\n- Git/file watchers for tools that ultimately change a repo.\n- Localhost browser capture, bookmarklets, and later browser extensions for web AI chats, issue pages, docs, and web clips.\n- App-specific adapters when a tool exposes logs, exports, plugins, or APIs.\n- Manual hotkey/clipboard capture as a low-friction fallback.\n\nAll adapters should emit the same event schema.\n\nMCP is a query adapter, not a promotion path. `rawmem-mcp` exposes only\npath-free status, bounded recent events, and archive metadata. Summary access\nis the default; raw bodies require an explicit `read:full` scope.\n\n## Privacy Principles\n\n- Local first.\n- No upload by default.\n- No automatic memory promotion.\n- Background capture must be opt-in.\n- Clipboard polling is off by default.\n- Browser capture requires the local token created in `~/.rawmem/config.json`.\n- The extension options page can test daemon connectivity and token acceptance.\n- Machine-wide Git hook setup requires `--yes`.\n- `rawmem uninstall` preserves captured data unless `--remove-home --yes` is explicit.\n- Store raw events separately from reviewed or derived memory.\n- Prefer allowlists for browser/app capture.\n\nSee [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md) before enabling\nbackground capture on a daily driver machine.\n\n## Development\n\n```powershell\n$env:PYTHONPATH = \"src\"\npython -m unittest discover -s tests\npython scripts/open_source_audit.py\n```\n",
  "bytes": 10005,
  "sha": "09e2f4feb1a431e762612e008e9d47b59ee1d72e0899f25961e478ed4329f4c3",
  "repo_slug": "liyuan1992/rawmem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_liyuan1992_rawmem_5b7e7f71/readme"
}