read-digests.mjs

// read-digests.mjs — the READ side (the economic payoff).
//
// Given a project, assemble its consolidated digests into a compact
// session-start context block, and report the token economics vs. injecting
// raw observations (which is what an append-only store does today).
//
// Token counts are estimates (chars / 4) — fine for an order-of-magnitude
// comparison. For exact counts, call your provider's count_tokens.
//
//   bun read-digests.mjs                 # list projects with digests
//   bun read-digests.mjs my-app          # context block + economics for my-app
//
// CONFIG (env)
//   CLAUDE_MEM_DB   path to the source observation store
//                   (default: ~/.claude-mem/claude-mem.db)
//   DIGEST_DB       path to the digest DB (default: ./digests.db)

import { Database } from "bun:sqlite";
import { homedir } from "os";
import { join } from "path";

const SOURCE_DB =
  process.env.CLAUDE_MEM_DB || join(homedir(), ".claude-mem", "claude-mem.db");
const DIGEST_DB = process.env.DIGEST_DB || join(process.cwd(), "digests.db");

const PROJECT = process.argv[2] || null;

// Logical reading order + human labels for the memory-type facets.
const TYPE_ORDER = [
  ["why-it-exists", "Why things exist"],
  ["how-it-works", "How it works"],
  ["pattern", "Patterns"],
  ["decision", "Decisions"],
  ["trade-off", "Trade-offs"],
  ["problem-solution", "Problems & solutions"],
  ["gotcha", "Gotchas"],
  ["what-changed", "Recent changes"],
];

const estTokens = (s) => Math.ceil((s || "").length / 4);

const dg = new Database(DIGEST_DB, { readonly: true });

// No project given: list what's available.
if (!PROJECT) {
  const rows = dg
    .query(
      `SELECT project, COUNT(*) cells, SUM(source_count) sources,
              SUM(LENGTH(digest)) chars
         FROM digests GROUP BY project ORDER BY sources DESC`
    )
    .all();
  console.log("Projects with digests:\n");
  console.log("project".padEnd(24) + "cells  sources  ~digest-tokens");
  for (const r of rows) {
    console.log(
      r.project.padEnd(24) +
        String(r.cells).padStart(5) +
        String(r.sources).padStart(9) +
        String(Math.ceil(r.chars / 4)).padStart(15)
    );
  }
  console.log("\nRun: bun read-digests.mjs <project>");
  dg.close();
  process.exit(0);
}

const cells = dg
  .query(
    `SELECT type, digest, source_count, version
       FROM digests WHERE project = ?`
  )
  .all(PROJECT);

if (cells.length === 0) {
  console.error(`No digests for project "${PROJECT}". Run build-digests first.`);
  process.exit(1);
}

const byType = new Map(cells.map((c) => [c.type, c]));

// ---------------------------------------------------------------------------
// THE INJECTABLE CONTEXT BLOCK — this is what would be fed at session start.
// ---------------------------------------------------------------------------
let block = `# Memory digest — ${PROJECT}\n`;
block += `_Consolidated understanding from prior sessions. Each section is an evolving digest, not a raw log._\n`;

let digestTokens = 0;
let digestSources = 0;
for (const [type, label] of TYPE_ORDER) {
  const cell = byType.get(type);
  if (!cell) continue;
  block += `\n## ${label}\n${cell.digest}\n`;
  digestTokens += estTokens(cell.digest);
  digestSources += cell.source_count;
}

// ---------------------------------------------------------------------------
// ECONOMICS — digest vs. raw observations for this project.
// ---------------------------------------------------------------------------
const src = new Database(SOURCE_DB, { readonly: true });
const raw = src
  .query(`SELECT title, narrative, facts FROM observations WHERE project = ?`)
  .all(PROJECT);

let rawTokens = 0;
for (const r of raw) {
  rawTokens += estTokens(r.title) + estTokens(r.narrative) + estTokens(r.facts);
}

// A common naive injection: up to 50 most-recent narratives.
const recent = src
  .query(
    `SELECT narrative FROM observations WHERE project = ?
       ORDER BY created_at_epoch DESC LIMIT 50`
  )
  .all(PROJECT);
let recentTokens = 0;
for (const r of recent) recentTokens += estTokens(r.narrative);

// Emit the context block to stdout (the deliverable), economics to stderr.
console.log(block);

const pct = (n, d) => (d ? ((100 * n) / d).toFixed(1) + "%" : "—");
console.error(`\n${"=".repeat(64)}`);
console.error(`ECONOMICS — ${PROJECT}  (token estimates, chars/4)`);
console.error("=".repeat(64));
console.error(
  `Digest block:      ~${digestTokens} tokens  (${cells.length} cells, ${digestSources} source observations consolidated)`
);
console.error(
  `All raw obs:       ~${rawTokens} tokens  (${raw.length} observations, full narrative+facts)`
);
console.error(
  `Naive recent-50:   ~${recentTokens} tokens  (50 most-recent narratives)`
);
console.error("-".repeat(64));
console.error(
  `Digest vs all-raw:        ${pct(digestTokens, rawTokens)} of the tokens  (${(rawTokens / Math.max(digestTokens, 1)).toFixed(1)}x compression)`
);
console.error(
  `Digest vs recent-50:      ${pct(digestTokens, recentTokens)}  — and the digest covers ALL ${raw.length} observations, not just 50`
);

dg.close();
src.close();