Mnemoscope is an MCP server that provides markdown-native, 100% local functionality for predicting context rot, signing every agent write, and tiering reads. It supports model-context-protocol (MCP) workflows and is oriented toward agent memory and LLM observability. It is associated with Obsidian and the Obsidian plugin ecosystem.
π οΈ Key Features
Predict context rot
Sign every agent write
Tier reads
Markdown-native, 100% local
π Use Cases
Agent memory tracking and evaluation
LLM observability via local, markdown-first workflows
Context-rot mitigation for agent interactions
Using MCP with Obsidian-based setups
β‘ Developer Benefits
Deterministic local behavior (β100% localβ)
Topic alignment for development around context-rot and agent-memory
Integration-ready for MCP clients and Obsidian plugins
β οΈ Limitations
Documentation excerpt provided does not specify deployment scope, supported LLM providers, or operational constraints.
An open-source observability layer for LLM agent memory on Markdown vaults. Predict context rot before it happens Β· audit every agent write with a signed journal Β· tier your knowledge the way the science says you should.
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). Mnemoscope is built on that distinction.
π See it in action
Real output, captured from the bundled 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).
predict_rot β score, factors, top-risk notes
mnemoscope-verify β clean run vs. tamper detection
Full overview (click) β gauge, factors, top-risk notes, both verify states, tier counts, hash chain β all on one page
β¨ What is Mnemoscope?
Mnemoscope 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:
π― Predict the rot risk of a corpus before injection, with a citation-backed score across 5 factors.
π Witness every read and write your agent performs, in an Ed25519-signed, hash-chained journal that detects field-level tampering, deletion, and reordering.
𧱠Tier the corpus into a working / episodic / semantic hierarchy, drawing on the 2025β2026 science instead of the GraphRAG hype.
It 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.
π How it fits your workflow
Imagine 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:
code
[create project]
β
βΌ
mnemoscope-init ββββ 1Γ at the very start
β creates .mnemoscope/, generates Ed25519 keypair
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [you work with Claude Code on the vault] β
β β
β predict_rot βββ β
β βββΊ on demand (or before sessions) β
β get_tiered_read βββ "is the vault healthy?" β
β "what should the agent read?" β
β β
β PostToolUse hook βββββΊ passive, on every Write/Edit β
β "what did the agent just do?" β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
mnemoscope-verify ββββ on demand, or in CI
"has anyone tampered?"
Phase
Tool / command
When to use it
What you get
1. Bootstrap
mnemoscope-init
Once, at project creation
.mnemoscope/ + per-vault Ed25519 keypair
2. Predict
predict_rot (MCP tool)
Before injecting a vault into the LLM
A 0β100 risk score + factor breakdown + top-risk notes
3. Compact
get_tiered_read (MCP tool)
When the vault grows past your model's effective context
The signed entry, including its sig, keyFingerprint, and prevHash
read_journal
vault_path, optional session_id
All journal entries, or a single session's entries
Example β predict_rot on a real vault
json
{"rot_risk":41,"dominant_factor":"tokenVolume","factors":{"tokenVolume":100,"semanticRedundancy":0,"distractorDensity":2.65,"structuralCoherence":100,"freshnessSpread":0},"top_risk_notes":[{"relPath":"brainstorms/.../transcript.md","approxTokens":13439,"reason":"very large note"},{"relPath":"brainstorms/.../sylvie-signaux.md","approxTokens":12605,"reason":"very large note"}],"vault_stats":{"noteCount":113,"approxTokens":506823},"baseline_model":"v0-heuristic","version":"0.2.0"}
π Quickstart
bash
git clone https://github.com/toonight/Mnemoscope
cd Mnemoscope
npm install
npm run build
npm test# 47 tests across core + mcp-server
npm audit # 0 vulnerabilities# Make the CLI binaries available on your PATH
npm link --workspace @mnemoscope/cli
Bootstrap a vault
bash
mnemoscope-init /path/to/your/vault
# β state dir, Ed25519 keypair, fingerprint
Add .mnemoscope/ to your vault's .gitignore β the per-vault private key must never be committed.
Connect the MCP server to Claude Code (or Cursor / any MCP client)
The 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.
Verify the journal
bash
mnemoscope-verify /path/to/vault
# ok 2026-04-26T19:42:13.001Z write /vault/notes/foo.md# ok 2026-04-26T19:43:01.220Z write /vault/notes/bar.md# 2 entries; 2 valid; 0 invalid
mnemoscope-verify exits non-zero on any of:
field-level tampering (signature mismatch),
deletion or reordering (prevHash chain break),
entries signed by a key the current vault does not own.
(Optional) back up the per-vault private key
If you lose <vault>/.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:
bash
mnemoscope-backup-key /path/to/vault /path/to/off-vault-backup.enc.json
# β¦ prompts for a passphrase, writes chmod 0600 β¦
mnemoscope-restore-key /path/to/vault /path/to/off-vault-backup.enc.json
# β¦ prompts for the same passphrase, writes the key back into the vault β¦
(Optional) anchor the journal in time with OpenTimestamps
The 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:
bash
mnemoscope-timestamp /path/to/vault
# β¦ POSTs SHA-256(sig) per entry to the calendar, writes .ots proofs# under <vault>/.mnemoscope/timestamps/. Idempotent on re-run.
Pending 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.
β What works today
What
How verified
β
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
β
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
β
record_journal produces a real Ed25519 signature with prevHash chaining
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
β
MCP server passes 5 end-to-end tests over real JSON-RPC stdio
server.test.ts spawns the binary
β
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
β
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
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
β
Three npm packages (@mnemoscope/{core,mcp-server,cli}@0.2.0) live on the public npm registry, published via OIDC Trusted Publishing (no rotating token, automatic provenance)
npm view @mnemoscope/core etc.; release workflow at .github/workflows/release.yml
β
The MCP server is listed on the Official MCP Registry under io.github.toonight/mnemoscope @ 0.2.0 β automatic fan-out to PulseMCP and other downstream catalogs
server.json at repo root, registered via mcp-publisher CLI
ποΈ Architecture
flowchart LR
A["Obsidian vault<br/>Markdown files"] --> B["mnemoscope/core<br/>signatures Β· rot Β· tiering Β· Ed25519 chained journal"]
B --> C["mnemoscope/mcp-server<br/>stdio MCP - 4 tools"]
B --> D["mnemoscope/obsidian-plugin<br/>UI Β· rot gauge"]
B --> G["mnemoscope/cli<br/>init Β· record-hook Β· verify"]
C -->|tools| E(("Claude Code<br/>Cursor<br/>ChatGPT desktop"))
G -->|PostToolUse hook| E
F["research/<br/>classifier Β· benchmark Β· replication"] -.->|trained ONNX classifier| B
style A fill:#1a2444,stroke:#a78bfa,color:#cbd5e1
style B fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
style C fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
style D fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
style G fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
style E fill:#1a2444,stroke:#7cf09d,color:#cbd5e1
style F fill:#1a2444,stroke:#fbbf24,color:#cbd5e1
If you maintain one of these projects and see overlap or complementarity, please open an issue β collaboration is the explicit design goal.
π¬ Scientific posture
Mnemoscope is meant to be a tool and a contribution to the public empirical record on agent memory.
Research thread
Status
Why it matters
MarkdownMemBench v0.1
π’ schema + sample dataset + harness shipping
Today's benchmarks (LongMemEval, LoCoMo) are conversational and English-only. There is no public bench for vault-native, MD-native agent memory.
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 > shuffled is worse" effect on real Markdown vaults graded by a real LLM (structural_coherence r = +0.30 vs observed loss). Audit metadata
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.
Replication of Chroma's "structured > shuffled is worse"
Chroma showed coherent haystacks underperform shuffled ones on NIAH. Nobody has replicated or refuted this on real Obsidian vaults yet. The runner (research/replication/) needs only an API key and a vault path.
Each thread lives in research/ and will produce a preprint alongside the code.
π£οΈ Roadmap
Done
Publish the three packages on npm at v0.2.0 with OIDC Trusted Publishing β @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.
List the MCP server on the Official MCP Registry β 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.
Submit the Obsidian plugin to the community plugins directory β obsidianmd/obsidian-releases#12354 passes automated validation; awaiting human review (typical 2β4 weeks).
Periodic remote attestation β OpenTimestamps anchoring of every journal-entry signature, upgradable to a Bitcoin-backed proof via the upstream ots CLI (docs/timestamping.md).
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 > shuffled is worse" effect on real Markdown vaults graded by a real LLM (model.json).
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.
Next
Dogfood the auto-journal hook on the author's vault for two full weeks; tune heuristics against observed Claude Code session outcomes
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
Release MarkdownMemBench v1 with 50β200 contributed real vaults
Preprint #1: replication of Chroma Context Rot on real Obsidian vaults
List on Glama (catalog ingestion path complementary to PulseMCP)
PRs are welcome but the most useful first step is opening an issue describing what you want to do. See CONTRIBUTING.md for code style and process.
If 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.
π License
Apache License 2.0. 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.
π Acknowledgements
Mnemoscope's framing borrows directly from public work by:
