{"id":50668892,"url":"https://github.com/toonight/mnemoscope","last_synced_at":"2026-06-08T09:01:13.310Z","repository":{"id":354258342,"uuid":"1222424980","full_name":"toonight/Mnemoscope","owner":"toonight","description":"Observability and predictive memory tooling for LLM agents on Markdown vaults — predictive context-rot scoring, Ed25519-signed hash-chained journal, hierarchical tiering. 100% local. MCP server + Obsidian plugin.","archived":false,"fork":false,"pushed_at":"2026-04-27T19:17:57.000Z","size":606,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T21:14:04.413Z","etag":null,"topics":["agent-memory","claude-code","context-rot","ed25519","llm-observability","markdown","mcp","model-context-protocol","obsidian","obsidian-plugin","opentimestamps","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/toonight/Mnemoscope","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toonight.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T10:59:20.000Z","updated_at":"2026-04-27T19:18:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toonight/Mnemoscope","commit_stats":null,"previous_names":["toonight/mnemoscope"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/toonight/Mnemoscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toonight%2FMnemoscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toonight%2FMnemoscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toonight%2FMnemoscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toonight%2FMnemoscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toonight","download_url":"https://codeload.github.com/toonight/Mnemoscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toonight%2FMnemoscope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34055249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","claude-code","context-rot","ed25519","llm-observability","markdown","mcp","model-context-protocol","obsidian","obsidian-plugin","opentimestamps","typescript"],"created_at":"2026-06-08T09:00:32.792Z","updated_at":"2026-06-08T09:01:13.303Z","avatar_url":"https://github.com/toonight.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./docs/banner.svg\" alt=\"Mnemoscope — See how your agent remembers (and forgets).\" width=\"100%\" /\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/toonight/Mnemoscope/blob/main/LICENSE\"\u003e\u003cimg alt=\"License: Apache-2.0\" src=\"https://img.shields.io/badge/license-Apache--2.0-2ea043?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg alt=\"Node 22+\" src=\"https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg alt=\"MCP\" src=\"https://img.shields.io/badge/MCP-server%20+%20Obsidian-5fd9d1?style=flat-square\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"100% local\" src=\"https://img.shields.io/badge/runs-100%25%20local-a78bfa?style=flat-square\"\u003e\n  \u003cimg alt=\"Version 0.2.0\" src=\"https://img.shields.io/badge/version-0.2.0-fbbf24?style=flat-square\"\u003e\n  \u003cimg alt=\"Tests: 61 passing\" src=\"https://img.shields.io/badge/tests-61%20passing-2ea043?style=flat-square\"\u003e\n  \u003cimg alt=\"0 vulnerabilities\" src=\"https://img.shields.io/badge/vulnerabilities-0-2ea043?style=flat-square\"\u003e\n  \u003ca href=\"https://github.com/toonight/Mnemoscope/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/toonight/Mnemoscope/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\u003cb\u003eAn open-source observability layer for LLM agent memory on Markdown vaults.\u003c/b\u003e\u003cbr/\u003e\n\u003ci\u003ePredict context rot before it happens · audit every agent write with a signed journal · tier your knowledge the way the science says you should.\u003c/i\u003e\u003c/p\u003e\n\n\u003csub\u003e\u003ca href=\"#-see-it-in-action\"\u003eDemo\u003c/a\u003e · \u003ca href=\"#-how-it-fits-your-workflow\"\u003eWorkflow\u003c/a\u003e · \u003ca href=\"#-the-four-mcp-tools\"\u003eTools\u003c/a\u003e · \u003ca href=\"#-quickstart\"\u003eQuickstart\u003c/a\u003e · \u003ca href=\"#%EF%B8%8F-architecture\"\u003eArchitecture\u003c/a\u003e · \u003ca href=\"#-scientific-posture\"\u003eScience\u003c/a\u003e\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003e [!NOTE]\n\u003e The dominant 2025–2026 narrative on X — *\"Markdown trips up the LLM at scale\"* — is partially wrong. **Markdown** does not trip up the LLM. **Long-context loading** trips up the LLM ([Chroma, *Context Rot*, July 2025](https://www.trychroma.com/research/context-rot)). Mnemoscope is built on that distinction.\n\n## 👀 See it in action\n\nReal output, captured from the bundled [`examples/demo-vault`](./examples/demo-vault) — a 13-note synthetic vault built so every rot factor moves. Reproduce locally with `mnemoscope-init examples/demo-vault` (full transcript: [SAMPLE-OUTPUT.md](./examples/demo-vault/SAMPLE-OUTPUT.md)).\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n**`predict_rot` — score, factors, top-risk notes**\n\n\u003cimg src=\"./docs/screenshots/predict-rot.png\" alt=\"predict_rot card showing rot risk 52/100, dominant factor semanticRedundancy, factor breakdown bars, and the top 5 risk notes.\" /\u003e\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n**`mnemoscope-verify` — clean run vs. tamper detection**\n\n\u003cimg src=\"./docs/screenshots/verify-clean-and-tampered.png\" alt=\"Two verify outputs side by side: a clean run with three valid entries and exit 0, and a tampered run with one signature-mismatch FAIL and exit 1.\" /\u003e\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFull overview (click) — gauge, factors, top-risk notes, both verify states, tier counts, hash chain — all on one page\u003c/summary\u003e\n\n\u003cimg src=\"./docs/screenshots/demo-overview.png\" alt=\"Full demo page showing every Mnemoscope view at once.\" /\u003e\n\n\u003c/details\u003e\n\n## ✨ What is Mnemoscope?\n\nMnemoscope is **not** another memory store. It is an **instrument** that sits between your LLM agent and your Markdown vault and gives you three things nobody else gives you in one tool:\n\n- 🎯 **Predict** the rot risk of a corpus *before* injection, with a citation-backed score across 5 factors.\n- 📝 **Witness** every read and write your agent performs, in an Ed25519-signed, hash-chained journal that detects field-level tampering, deletion, and reordering.\n- 🧱 **Tier** the corpus into a working / episodic / semantic hierarchy, drawing on the 2025–2026 science instead of the GraphRAG hype.\n\nIt ships as an **MCP server** (Claude Code, Cursor, ChatGPT desktop, anything MCP-compatible), an **Obsidian plugin**, and a **Claude Code `PostToolUse` hook**. Everything runs **100% locally**. No cloud. No telemetry without explicit opt-in.\n\n## 🔄 How it fits your workflow\n\nImagine you start a brand-new project — a folder of Markdown notes you'll grow with Claude Code over the next year. Mnemoscope plugs into the lifecycle in five places:\n\n```\n   [create project]\n        │\n        ▼\n   mnemoscope-init                     ◄─── 1× at the very start\n        │                                   creates .mnemoscope/, generates Ed25519 keypair\n        ▼\n   ┌───────────────────────────────────────────────────────────┐\n   │  [you work with Claude Code on the vault]                 │\n   │                                                           │\n   │   predict_rot       ──┐                                   │\n   │                       ├─►  on demand (or before sessions) │\n   │   get_tiered_read   ──┘    \"is the vault healthy?\"        │\n   │                            \"what should the agent read?\"  │\n   │                                                           │\n   │   PostToolUse hook  ────►  passive, on every Write/Edit   │\n   │                            \"what did the agent just do?\"  │\n   └───────────────────────────────────────────────────────────┘\n        │\n        ▼\n   mnemoscope-verify                   ◄─── on demand, or in CI\n                                            \"has anyone tampered?\"\n```\n\n| Phase | Tool / command | When to use it | What you get |\n|---|---|---|---|\n| 1. **Bootstrap** | `mnemoscope-init` | Once, at project creation | `.mnemoscope/` + per-vault Ed25519 keypair |\n| 2. **Predict** | `predict_rot` (MCP tool) | Before injecting a vault into the LLM | A 0–100 risk score + factor breakdown + top-risk notes |\n| 3. **Compact** | `get_tiered_read` (MCP tool) | When the vault grows past your model's effective context | Working / episodic / semantic split |\n| 4. **Witness** | `mnemoscope-record-hook` (Claude Code PostToolUse hook) | Wired once in `~/.claude/settings.json`, then **passive** | Every agent write becomes a signed journal entry |\n| 5. **Audit** | `mnemoscope-verify` | Any time, or as a pre-commit / CI step | Exit 0 if all entries verify, exit 1 if tampered |\n\n## 🛠️ The four MCP tools\n\n| Tool | Input | What it returns |\n|---|---|---|\n| `predict_rot` | `vault_path` | Score 0–100, dominant factor, full factor breakdown, top 5 risk notes, vault stats |\n| `get_tiered_read` | `vault_path`, optional age thresholds | Note paths grouped into `working` / `episodic` / `semantic` |\n| `record_journal` | `vault_path`, `session_id`, `op`, `target_path`, optional content | The signed entry, including its `sig`, `keyFingerprint`, and `prevHash` |\n| `read_journal` | `vault_path`, optional `session_id` | All journal entries, or a single session's entries |\n\n#### Example — `predict_rot` on a real vault\n\n```json\n{\n  \"rot_risk\": 41,\n  \"dominant_factor\": \"tokenVolume\",\n  \"factors\": {\n    \"tokenVolume\": 100, \"semanticRedundancy\": 0,\n    \"distractorDensity\": 2.65, \"structuralCoherence\": 100, \"freshnessSpread\": 0\n  },\n  \"top_risk_notes\": [\n    { \"relPath\": \"brainstorms/.../transcript.md\", \"approxTokens\": 13439, \"reason\": \"very large note\" },\n    { \"relPath\": \"brainstorms/.../sylvie-signaux.md\", \"approxTokens\": 12605, \"reason\": \"very large note\" }\n  ],\n  \"vault_stats\": { \"noteCount\": 113, \"approxTokens\": 506823 },\n  \"baseline_model\": \"v0-heuristic\",\n  \"version\": \"0.2.0\"\n}\n```\n\n## 🚀 Quickstart\n\n```bash\ngit clone https://github.com/toonight/Mnemoscope\ncd Mnemoscope\nnpm install\nnpm run build\nnpm test                           # 47 tests across core + mcp-server\nnpm audit                          # 0 vulnerabilities\n\n# Make the CLI binaries available on your PATH\nnpm link --workspace @mnemoscope/cli\n```\n\n### Bootstrap a vault\n\n```bash\nmnemoscope-init /path/to/your/vault\n# → state dir, Ed25519 keypair, fingerprint\n```\n\n\u003e Add `.mnemoscope/` to your vault's `.gitignore` — the per-vault private key must never be committed.\n\n### Connect the MCP server to Claude Code (or Cursor / any MCP client)\n\n```json\n// ~/.claude/settings.json\n{\n  \"mcpServers\": {\n    \"mnemoscope\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/Mnemoscope/packages/mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\nThe four tools (`predict_rot`, `get_tiered_read`, `record_journal`, `read_journal`) become available to the agent immediately.\n\n### (Optional) wire the auto-journal hook\n\nAsking the agent to call `record_journal` on every write is a recipe for forgetting. Wire the bundled hook instead:\n\n```json\n// ~/.claude/settings.json\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Write|Edit|MultiEdit\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"mnemoscope-record-hook\" }]\n      }\n    ]\n  }\n}\n```\n\nThe hook resolves the vault root via `MNEMOSCOPE_VAULT_PATH` or by walking up to the closest `.mnemoscope/` directory. It **never blocks** the tool call: any internal error is caught, logged to stderr, and the process exits 0. Full setup including safety properties: [docs/claude-code-hook.md](./docs/claude-code-hook.md).\n\n### Verify the journal\n\n```bash\nmnemoscope-verify /path/to/vault\n# ok    2026-04-26T19:42:13.001Z  write  /vault/notes/foo.md\n# ok    2026-04-26T19:43:01.220Z  write  /vault/notes/bar.md\n# 2 entries; 2 valid; 0 invalid\n```\n\n`mnemoscope-verify` exits non-zero on any of:\n\n- field-level tampering (signature mismatch),\n- deletion or reordering (`prevHash` chain break),\n- entries signed by a key the current vault does not own.\n\n### (Optional) back up the per-vault private key\n\nIf you lose `\u003cvault\u003e/.mnemoscope/keys/ed25519.key`, the journal becomes unverifiable. The bundled backup CLIs encrypt the key with a passphrase (scrypt + AES-256-GCM, no extra deps) and let you restore it later:\n\n```bash\nmnemoscope-backup-key /path/to/vault /path/to/off-vault-backup.enc.json\n# … prompts for a passphrase, writes chmod 0600 …\n\nmnemoscope-restore-key /path/to/vault /path/to/off-vault-backup.enc.json\n# … prompts for the same passphrase, writes the key back into the vault …\n```\n\nFull flow including threat model: [docs/key-escrow.md](./docs/key-escrow.md).\n\n### (Optional) anchor the journal in time with OpenTimestamps\n\nThe signed hash chain proves *order*. To prove *absolute time* and stay safe against retroactive rewrites if the per-vault key is ever compromised, anchor each entry's signature to a public Bitcoin-backed OTS calendar:\n\n```bash\nmnemoscope-timestamp /path/to/vault\n# … POSTs SHA-256(sig) per entry to the calendar, writes .ots proofs\n# under \u003cvault\u003e/.mnemoscope/timestamps/. Idempotent on re-run.\n```\n\nPending proofs are upgraded to fully self-verifying Bitcoin proofs with the upstream `ots upgrade` / `ots verify` CLIs — that part is intentionally not reimplemented. Full threat model and flow: [docs/timestamping.md](./docs/timestamping.md).\n\n## ✅ What works today\n\n| | What | How verified |\n|---|---|---|\n| ✅ | `predict_rot` returns a 5-factor breakdown, each factor citation-backed in source | 14 unit tests; smoke-tested on a real 506 K-token vault — sensible top-risk ordering |\n| ✅ | `get_tiered_read` splits a vault into working / episodic / semantic by freshness | integration test on fixture vault; freshness-based, access-frequency aware in a future revision |\n| ✅ | `record_journal` produces a real **Ed25519** signature with **prevHash** chaining | 9 journal tests, including 4 tamper tests + 2 chain-integrity tests (truncation, reordering) |\n| ✅ | `mnemoscope-init` bootstraps a vault idempotently | manual run on multiple fresh + existing vaults |\n| ✅ | `mnemoscope-verify` CLI replays and exits non-zero on any invalid entry | wired to the same `verifyAll` |\n| ✅ | `mnemoscope-record-hook` Claude Code `PostToolUse` hook auto-journals every Write/Edit/MultiEdit | [docs/claude-code-hook.md](./docs/claude-code-hook.md), never blocks |\n| ✅ | `mnemoscope-backup-key` / `mnemoscope-restore-key` encrypt the per-vault Ed25519 key with scrypt + AES-256-GCM | 7 unit tests, full flow in [docs/key-escrow.md](./docs/key-escrow.md) |\n| ✅ | `mnemoscope-timestamp` anchors each entry's signature to a Bitcoin-backed OpenTimestamps calendar; pending `.ots` proofs upgraded with the official `ots` CLI | 12 unit tests + smoke-tested 3 entries → 3 `.ots` files round-trip through `verifyOtsHeaderForDigest`; full flow in [docs/timestamping.md](./docs/timestamping.md) |\n| ✅ | MCP server passes 5 end-to-end tests over real JSON-RPC stdio | `server.test.ts` spawns the binary |\n| ✅ | Obsidian plugin: sidebar view with SVG rot gauge, factor bars, top-risk list, settings tab, auto-onboarding modal on first launch | single-file bundle, no runtime deps; `eslint-plugin-obsidianmd` clean in CI |\n| ✅ | Research sub-project: predictive classifier **calibrated on real LLM measurements** (Random Forest R² = 0.58 on 50 rows graded by Gemma 4 26B), MarkdownMemBench v0.1 schema + sample dataset + harness, Chroma replication protocol with position-of-needle sweep | self-contained Python project under [`research/`](./research); CI runs `ruff` + 14 pytest cases on every push; classifier metadata audited in [`research/classifier/model.json`](./research/classifier/model.json) |\n| ✅ | CI green on Node 22 + Python 3.11, **0 npm vulnerabilities**, `npm audit --audit-level=moderate` and `eslint-plugin-obsidianmd` enforced on every push | GitHub Actions on every push and PR |\n| ✅ | Three npm packages (`@mnemoscope/{core,mcp-server,cli}@0.2.0`) live on the public npm registry, published via [OIDC Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) (no rotating token, automatic provenance) | `npm view @mnemoscope/core` etc.; release workflow at `.github/workflows/release.yml` |\n| ✅ | The MCP server is listed on the [Official MCP Registry](https://registry.modelcontextprotocol.io/) under `io.github.toonight/mnemoscope @ 0.2.0` — automatic fan-out to PulseMCP and other downstream catalogs | [`server.json`](./server.json) at repo root, registered via `mcp-publisher` CLI |\n\n## 🏗️ Architecture\n\n```mermaid\nflowchart LR\n    A[\"Obsidian vault\u003cbr/\u003eMarkdown files\"] --\u003e B[\"mnemoscope/core\u003cbr/\u003esignatures · rot · tiering · Ed25519 chained journal\"]\n    B --\u003e C[\"mnemoscope/mcp-server\u003cbr/\u003estdio MCP - 4 tools\"]\n    B --\u003e D[\"mnemoscope/obsidian-plugin\u003cbr/\u003eUI · rot gauge\"]\n    B --\u003e G[\"mnemoscope/cli\u003cbr/\u003einit · record-hook · verify\"]\n    C --\u003e|tools| E((\"Claude Code\u003cbr/\u003eCursor\u003cbr/\u003eChatGPT desktop\"))\n    G --\u003e|PostToolUse hook| E\n    F[\"research/\u003cbr/\u003eclassifier · benchmark · replication\"] -.-\u003e|trained ONNX classifier| B\n    style A fill:#1a2444,stroke:#a78bfa,color:#cbd5e1\n    style B fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style C fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style D fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style G fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style E fill:#1a2444,stroke:#7cf09d,color:#cbd5e1\n    style F fill:#1a2444,stroke:#fbbf24,color:#cbd5e1\n```\n\n```\nmnemoscope/\n├── packages/\n│   ├── core/              # rot scoring, tiering, Ed25519 hash-chained journal, signatures\n│   ├── mcp-server/        # MCP server (stdio); 4 tools, integration-tested via spawn\n│   ├── obsidian-plugin/   # Obsidian plugin: rot gauge, factor bars, top-risk list, settings\n│   └── cli/               # mnemoscope-init, mnemoscope-record-hook, mnemoscope-verify\n├── examples/\n│   └── demo-vault/        # 13-note synthetic vault — every rot factor moves\n├── research/              # Python (uv): classifier, MarkdownMemBench v0.1, Chroma replication\n└── docs/                  # banner, logo, claude-code-hook setup, demo page, screenshots\n```\n\n## 🔐 The signed journal in one diagram\n\n```mermaid\nflowchart TD\n    K[\"Per-vault Ed25519 keypair\u003cbr/\u003e.mnemoscope/keys/ed25519.key (mode 0600)\"]\n    E1[\"Entry 1\u003cbr/\u003eprevHash = GENESIS\u003cbr/\u003esig = σ1\"]\n    E2[\"Entry 2\u003cbr/\u003eprevHash = SHA256 of σ1\u003cbr/\u003esig = σ2\"]\n    E3[\"Entry 3\u003cbr/\u003eprevHash = SHA256 of σ2\u003cbr/\u003esig = σ3\"]\n    K --\u003e|signs| E1\n    K --\u003e|signs| E2\n    K --\u003e|signs| E3\n    E1 -.-\u003e|chain| E2\n    E2 -.-\u003e|chain| E3\n    style K fill:#1a2444,stroke:#a78bfa,color:#cbd5e1\n    style E1 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style E2 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n    style E3 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1\n```\n\n| Attack | Detected by |\n|---|---|\n| Edit a field of any single entry | per-entry signature mismatch |\n| Delete an entry | next entry's `prevHash` no longer matches |\n| Reorder two entries | both signatures still verify, but the chain breaks |\n| Forge an entry with a different key | `keyFingerprint` flagged as foreign |\n\n## 🤝 Voisins (not competitors)\n\n| Project | What it does | Where Mnemoscope sits |\n|---|---|---|\n| [Anthropic Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) | Official, file-based, primitive | We add the rot scoring + signed chained journal Anthropic does not provide |\n| [Letta](https://letta.com) / [MemGPT](https://github.com/letta-ai/letta) | Runtime-stateful agents | Different layer — we sit *under* the agent |\n| [Mem0](https://mem0.ai), [Zep](https://getzep.com), [Cognee](https://cognee.ai) | Generic memory stores | Different scope — we are MD-vault-native |\n| [MemPalace](https://mempalace.tech) | Viral OSS memory MCP | Not Obsidian-specific; complementary |\n| [Smart Connections](https://smartconnections.app) | RAG-vector for Obsidian | Co-installable; we are runtime / forensics, they are search |\n| [Basic Memory MCP](https://github.com/basicmachines-co/basic-memory) | Semantic graph over markdown | Closest in spirit — we want to interop, not duplicate |\n| [claude-memory-compiler](https://github.com/coleam00/claude-memory-compiler) | MD-compiler approach | Reach out before duplicating |\n\n\u003e [!IMPORTANT]\n\u003e If you maintain one of these projects and see overlap or complementarity, please [open an issue](https://github.com/toonight/Mnemoscope/issues/new) — collaboration is the explicit design goal.\n\n## 🔬 Scientific posture\n\nMnemoscope is meant to be a tool **and** a contribution to the public empirical record on agent memory.\n\n| Research thread | Status | Why it matters |\n|---|---|---|\n| **MarkdownMemBench v0.1** | 🟢 schema + sample dataset + harness shipping | Today's benchmarks ([LongMemEval](https://arxiv.org/pdf/2410.10813), [LoCoMo](https://snap-research.github.io/locomo/)) are conversational and English-only. There is no public bench for vault-native, MD-native agent memory. |\n| **Predictive Context Rot classifier** | 🟢 trained on **50 real `(signature, observed_loss)` rows** graded by `gemma4:26b` (Q4_K_M, `num_ctx=40000`). Random Forest wins out — **R² = 0.58, MAE = 0.14** on a held-out 10-row split — confirming the rot surface has interactions a linear model can't capture (Ridge collapses from 0.85 on the synthetic baseline to 0.14 on real data). First public observation of Chroma 2025's \"structured \u003e shuffled is worse\" effect on real Markdown vaults graded by a real LLM (`structural_coherence` r = +0.30 vs observed loss). [Audit metadata](./research/classifier/model.json) | Every existing benchmark measures degradation *after* injection. We predict it *before*, with a calibrated baseline anyone can extend by dropping a fresh `measurements.csv` next to the existing one and re-training. |\n| **Replication of Chroma's *\"structured \u003e shuffled is worse\"*** | 🟢 runner + offline \u0026 online grading shipping; real-corpus runs pending vault contributions | Chroma showed coherent haystacks underperform shuffled ones on NIAH. Nobody has replicated or refuted this on real Obsidian vaults yet. The runner ([`research/replication/`](./research/replication)) needs only an API key and a vault path. |\n\nEach thread lives in [`research/`](./research) and will produce a preprint alongside the code.\n\n## 🛣️ Roadmap\n\n### Done\n\n- [x] **Publish the three packages on npm at v0.2.0** with [OIDC Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) — `@mnemoscope/{core,mcp-server,cli}` are live on the npm registry. CI publishes automatically on tag push, no rotating token required, provenance attestations emitted on every publish.\n- [x] **List the MCP server on the [Official MCP Registry](https://registry.modelcontextprotocol.io/)** — `io.github.toonight/mnemoscope @ 0.2.0` is indexed. PulseMCP ingests the official registry daily, so the server appears there too within ~7 days, no separate submission required.\n- [x] **Submit the Obsidian plugin to the community plugins directory** — [obsidianmd/obsidian-releases#12354](https://github.com/obsidianmd/obsidian-releases/pull/12354) passes automated validation; awaiting human review (typical 2–4 weeks).\n- [x] **Periodic remote attestation** — OpenTimestamps anchoring of every journal-entry signature, upgradable to a Bitcoin-backed proof via the upstream `ots` CLI ([docs/timestamping.md](./docs/timestamping.md)).\n- [x] **Calibrate the predictive classifier on real LLM measurements** — 50 `(signature, observed_loss)` rows graded by `gemma4:26b`, Random Forest wins at R² = 0.58 / MAE = 0.14 on the held-out split; first public observation of the Chroma 2025 \"structured \u003e shuffled is worse\" effect on real Markdown vaults graded by a real LLM ([model.json](./research/classifier/model.json)).\n- [x] **Lint locally with the same plugin the Obsidian reviewer uses** — `eslint-plugin-obsidianmd` is wired into the project (root `eslint.config.mjs`, `npm run lint`) and gates CI, so reviewer-bot findings land at commit time instead of review time.\n\n### Next\n\n- [ ] Dogfood the auto-journal hook on the author's vault for two full weeks; tune heuristics against observed Claude Code session outcomes\n- [ ] Wire the calibrated `model.onnx` into `@mnemoscope/core` via `onnxruntime-node` (optional dependency) so `predict_rot` returns the model's prediction next to the v0 heuristic\n- [ ] Release **MarkdownMemBench v1** with 50–200 contributed real vaults\n- [ ] Preprint #1: replication of Chroma *Context Rot* on real Obsidian vaults\n- [ ] List on [Glama](https://glama.ai/mcp) (catalog ingestion path complementary to PulseMCP)\n\nFull history: [CHANGELOG.md](./CHANGELOG.md).\n\n## 🧑‍🤝‍🧑 Contributing\n\nPRs are welcome but the most useful first step is opening an issue describing what you want to do. See [CONTRIBUTING.md](./CONTRIBUTING.md) for code style and process.\n\nIf you are a **researcher** at Letta, Chroma, Mem0, Cognee, OSU-NLP, Snap Research or any related lab and you see overlap with the *Predictive Context Rot* or *MarkdownMemBench* axes, please reach out — the project is explicitly designed for this.\n\n## 📜 License\n\n[Apache License 2.0](./LICENSE). Apache-2.0 was chosen over MIT for its explicit patent grant, which we believe is appropriate for a project introducing novel scoring methods in an active research area.\n\n## 🙏 Acknowledgements\n\nMnemoscope's framing borrows directly from public work by:\n\n- [Chroma Research — *Context Rot* (July 2025)](https://www.trychroma.com/research/context-rot)\n- [Letta — *Is a Filesystem All You Need?* (August 2025)](https://www.letta.com/blog/benchmarking-ai-agent-memory)\n- [Letta — *Sleep-time Compute* (2025)](https://www.letta.com/blog/sleep-time-compute)\n- [Microsoft — *LazyGraphRAG* (June 2025)](https://www.microsoft.com/en-us/research/blog/lazygraphrag-setting-a-new-standard-for-quality-and-cost/)\n- [HippoRAG (NeurIPS'24, OSU-NLP)](https://github.com/osu-nlp-group/hipporag)\n- [LongMemEval (ICLR 2025)](https://arxiv.org/pdf/2410.10813)\n- [LoCoMo (Snap Research)](https://snap-research.github.io/locomo/)\n- [Liu et al., *Lost in the Middle* (2023)](https://arxiv.org/abs/2307.03172)\n- [Andrej Karpathy's LLM Wiki proposal (April 2026)](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2)\n\nWithout their public artifacts, this project would not be possible.\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003e🧠  \u003ccode\u003epredict · witness · tier\u003c/code\u003e  🧠\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoonight%2Fmnemoscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoonight%2Fmnemoscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoonight%2Fmnemoscope/lists"}