Mnemoscope

   [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?"

{
  "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.1.0"
}

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

mnemoscope-init /path/to/your/vault
# → state dir, Ed25519 keypair, fingerprint

// ~/.claude/settings.json
{
  "mcpServers": {
    "mnemoscope": {
      "command": "node",
      "args": ["/absolute/path/to/Mnemoscope/packages/mcp-server/dist/index.js"]
    }
  }
}

// ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "mnemoscope-record-hook" }]
      }
    ]
  }
}

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-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 …

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.

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

mnemoscope/
├── packages/
│   ├── core/              # rot scoring, tiering, Ed25519 hash-chained journal, signatures
│   ├── mcp-server/        # MCP server (stdio); 4 tools, integration-tested via spawn
│   ├── obsidian-plugin/   # Obsidian plugin: rot gauge, factor bars, top-risk list, settings
│   └── cli/               # mnemoscope-init, mnemoscope-record-hook, mnemoscope-verify
├── examples/
│   └── demo-vault/        # 13-note synthetic vault — every rot factor moves
├── research/              # Python (uv): classifier, MarkdownMemBench v0.1, Chroma replication
└── docs/                  # banner, logo, claude-code-hook setup, demo page, screenshots

flowchart TD
    K["Per-vault Ed25519 keypair<br/>.mnemoscope/keys/ed25519.key (mode 0600)"]
    E1["Entry 1<br/>prevHash = GENESIS<br/>sig = σ1"]
    E2["Entry 2<br/>prevHash = SHA256 of σ1<br/>sig = σ2"]
    E3["Entry 3<br/>prevHash = SHA256 of σ2<br/>sig = σ3"]
    K -->|signs| E1
    K -->|signs| E2
    K -->|signs| E3
    E1 -.->|chain| E2
    E2 -.->|chain| E3
    style K fill:#1a2444,stroke:#a78bfa,color:#cbd5e1
    style E1 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
    style E2 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1
    style E3 fill:#0e1530,stroke:#5fd9d1,color:#cbd5e1