openviking-memory

1import type { EngineInterface, Register, ResolveInput } from "claude-code";
2import type { Lookup, Turn } from "./types";
3import {
4  ICON,
5  classifyCall,
6  consulted,
7  groupOf,
8  hashText,
9  parseRecall,
10  summaryLine,
11  titleOf,
12  urisIn,
13} from "./sources";
14
15const turnsRef = { plugin: "openviking-memory", key: "turns" } as const;
16const repliesRef = { plugin: "openviking-memory", key: "replies" } as const;
17const expandedRef = { plugin: "openviking-memory", key: "expanded" } as const;
18
19const MAX_TURNS = 50;
20const MAX_SESSIONS = 20;
21const ACCENT = "cyan";
22
23// Card bookkeeping must never break the memory hooks it watches: a failure here
24// is logged to the debug log and the hook's own result goes through unchanged.
25async function safely<T>($: EngineInterface, what: string, fn: () => Promise<T>): Promise<T | undefined> {
26  try {
27    return await fn();
28  } catch (err) {
29    $.ui.log(`openviking-usage: ${what} failed: ${err instanceof Error ? err.message : String(err)}`, {
30      to: "debug",
31    });
32    return undefined;
33  }
34}
35
36// Read, change, write back against the version read: tool calls run in parallel.
37async function editTurns($: EngineInterface, fn: (turns: Turn[]) => Turn[]) {
38  for (let i = 0; i < 10; i++) {
39    const held = await $.state.get(turnsRef);
40    const { isSet } = await $.state.set(turnsRef, fn(held.value ?? []), {
41      ifVersion: held.version,
42    });
43    if (isSet) return;
44  }
45}
46
47async function lastTurn($: EngineInterface): Promise<Turn | undefined> {
48  const { value = [] } = await $.state.get(turnsRef);
49  return value.at(-1);
50}
51
52// $.state is lost when the process restarts; $.store keeps each session's cards
53// so `claude --continue` draws them again.
54async function save($: EngineInterface) {
55  const id = await $.session.id();
56  if (!id) return;
57  await $.store.set(`usage:session:${id}`, {
58    turns: (await $.state.get(turnsRef)).value ?? [],
59    replies: (await $.state.get(repliesRef)).value ?? [],
60    expanded: (await $.state.get(expandedRef)).value ?? [],
61  });
62  const index = ((await $.store.get("usage:sessions")) as string[] | undefined) ?? [];
63  const next = [...index.filter((k) => k !== id), id];
64  for (const old of next.slice(0, -MAX_SESSIONS)) await $.store.delete(`usage:session:${old}`);
65  await $.store.set("usage:sessions", next.slice(-MAX_SESSIONS));
66}
67
68async function restore($: EngineInterface) {
69  if ((await $.state.get(turnsRef)).value?.length) return; // a hot reload keeps $.state
70  const id = await $.session.id();
71  const snap = id
72    ? ((await $.store.get(`usage:session:${id}`)) as Record<string, never> | undefined)
73    : undefined;
74  if (!snap) return;
75  await $.state.set(turnsRef, snap.turns ?? []);
76  await $.state.set(repliesRef, snap.replies ?? []);
77  await $.state.set(expandedRef, snap.expanded ?? []);
78}
79
80async function setExpanded($: EngineInterface, n: number | "all", isOpen: boolean) {
81  const { value: turns = [] } = await $.state.get(turnsRef);
82  const { value: list = [] } = await $.state.get(expandedRef);
83  const which = n === "all" ? turns.map((t) => t.n) : [n];
84  await $.state.set(
85    expandedRef,
86    isOpen ? [...new Set([...list, ...which])] : list.filter((x) => !which.includes(x)),
87  );
88  await save($);
89}
90
91// The card under an answer: one line of totals, or that line plus every source
92// and Claude's own lookups. Nothing when the answer drew on nothing.
93async function card($: EngineInterface, e: ResolveInput, turn: Turn) {
94  const { Box, Text, Button } = $.ui.resolve(e);
95  const c = consulted(turn);
96  const lookups = turn.lookups;
97  if (c.rows.length === 0 && lookups.length === 0) return null;
98  const { value: expanded = [] } = await $.state.get(expandedRef);
99  const isOpen = expanded.includes(turn.n);
100  return (
101    <Box flexDirection="column" marginLeft={2} marginTop={1}>
102      <Box flexWrap="wrap" columnGap={2}>
103        <Text color={ACCENT} wrap="wrap">
104          {summaryLine(c)}
105        </Text>
106        <Button
107          key={`ov-toggle-${turn.n}`}
108          label={isOpen ? "[Collapse]" : "[Expand]"}
109          plain
110          onPress={() => setExpanded($, turn.n, !isOpen)}
111        />
112      </Box>
113      {isOpen &&
114        c.rows.map((r) => (
115          <Text key={`ov-src-${turn.n}-${r.uri}`} wrap="wrap">
116            {"  "}
117            {ICON[groupOf(r.uri)]} {titleOf(r.uri)}
118            <Text dimColor>
119              {r.from === "recall"
120                ? ` · auto-recalled${r.score > 0 ? ` ${r.score.toFixed(2)}` : ""}`
121                : " · found by Claude"}
122              {r.isOpened ? " · read in full" : ""}
123            </Text>
124          </Text>
125        ))}
126      {isOpen && lookups.length > 0 && <Text bold>Claude's own lookups</Text>}
127      {isOpen &&
128        lookups.map((l) => (
129          <Text key={`ov-lookup-${l.id}`} wrap="wrap">
130            {"  "}
131            {l.query !== null ? `⌕ Searched “${l.query}” · ${l.found.length} results` : ""}
132            {l.query !== null && l.opened.length ? " · " : ""}
133            {l.opened.length ? `▤ Read ${l.opened.map(titleOf).join(", ")}` : ""}
134            {l.isError && <Text color="red"> · failed</Text>}
135          </Text>
136        ))}
137    </Box>
138  );
139}
140
141export const register: Register = (on) => {
142  on("session.start", async ($, e, next) => {
143    await safely($, "restore", () => restore($));
144    await $.command.register({
145      name: "openviking-usage",
146      description: "Expand or collapse the OpenViking cards under answers",
147      argumentHint: "expand | collapse",
148    });
149    return next(e);
150  });
151
152  on("command.run", { command: "openviking-usage" }, async ($, e) => {
153    const verb = e.args.trim().toLowerCase();
154    if (verb === "expand" || verb === "collapse") {
155      await setExpanded($, "all", verb === "expand");
156      return {};
157    }
158    return { text: "Usage: /openviking-usage expand | collapse" };
159  });
160
161  // Each prompt starts an answer; openviking-memory's recall block says what it injected.
162  on("classic.UserPromptSubmit", async ($, e, next) => {
163    const res = await next(e);
164    await safely($, "record prompt", async () => {
165      const block = (res.additionalContext ?? []).find(
166        (c) =>
167          c.includes("<openviking-context") &&
168          !/source="(startup|resume|compact|skill-experience)"/.test(c),
169      );
170      const prev = await lastTurn($);
171      const turn: Turn = {
172        n: (prev?.n ?? 0) + 1,
173        recalled: block ? parseRecall(block) : [],
174        lookups: [],
175      };
176      await editTurns($, (list) => [...list, turn].slice(-MAX_TURNS));
177      await save($);
178    });
179    return res;
180  });
181
182  // Claude's own OpenViking reads and searches, through MCP or the `ov` CLI.
183  on("tool.call", async ($, e, next) => {
184    const found = await safely($, "classify tool call", async () => {
185      const call = classifyCall(e.tool, { ...e } as Record<string, unknown>);
186      const turn = call ? await lastTurn($) : undefined;
187      return call && turn ? { call, turn } : undefined;
188    });
189    if (!found) return next(e);
190    const { call, turn } = found;
191    const ran = await next(e);
192    await safely($, "record lookup", async () => {
193      const text = "text" in ran && typeof ran.text === "string" ? ran.text : "";
194      const lookup: Lookup = {
195        id: e.tool_use_id,
196        query: call.query,
197        opened: call.opened,
198        found: call.query !== null ? urisIn(text).filter((u) => !call.opened.includes(u)) : [],
199        isError: ran.deny !== undefined || ran.isError === true,
200      };
201      await editTurns($, (list) =>
202        list.map((t) => (t.n === turn.n ? { ...t, lookups: [...t.lookups, lookup] } : t)),
203      );
204    });
205    return ran;
206  });
207
208  // The last text row of an answer carries its card.
209  on("session.append", async ($, e, next) => {
210    const res = await next(e);
211    if (res.deny !== undefined || e.agentId || e.door !== "response") return res;
212    await safely($, "record reply", async () => {
213      const texts = (res.message.content ?? []).filter(
214        (b): b is { type: "text"; text: string } =>
215          !!b && typeof b === "object" && "type" in b && b.type === "text" && "text" in b,
216      );
217      const last = texts.at(-1);
218      const turn = last ? await lastTurn($) : undefined;
219      if (last && turn) {
220        const { value: list = [] } = await $.state.get(repliesRef);
221        const reply = { id: res.uuid, n: turn.n, text: hashText(last.text) };
222        const kept = [...list.filter((r) => r.n !== turn.n), reply];
223        await $.state.set(repliesRef, kept.slice(-MAX_TURNS));
224      }
225    });
226    return res;
227  });
228
229  on("turn.complete", async ($, e, next) => {
230    const done = await next(e);
231    await safely($, "save", () => save($));
232    return done;
233  });
234
235  on("ui.render", { component: "AssistantMessage" }, async ($, e, next) => {
236    const below = await safely($, "draw card", async () => {
237      const { value: replies = [] } = await $.state.get(repliesRef);
238      // The terminal names the row by its uuid; the desktop by API message id, so
239      // fall back to the reply's text.
240      const text = typeof e.props.text === "string" ? hashText(e.props.text) : undefined;
241      const n = (
242        replies.find((r) => r.id === e.requestId) ??
243        (text ? replies.find((r) => r.text === text) : undefined)
244      )?.n;
245      const { value: turns = [] } = await $.state.get(turnsRef);
246      const turn = n === undefined ? undefined : turns.find((t) => t.n === n);
247      return turn ? await card($, e, turn) : null;
248    });
249    if (!below) return next(e);
250    const { Box } = $.ui.resolve(e);
251    return (
252      <Box flexDirection="column">
253        {await next(e)}
254        {below}
255      </Box>
256    );
257  });
258};
259

1// Pure helpers: which viking:// URIs a recall block or a tool call names, which
2// tool calls are OpenViking lookups, and what one answer consulted.
3
4import type { Lookup, Turn } from "./types";
5
6// A viking:// URI stops at whitespace, quotes, brackets or CJK punctuation.
7const URI = /viking:\/\/(?:~|[A-Za-z][\w.-]*)(?:\/[^\s"'<>)\]`,，。；：！？、（）《》“”]*)?/g;
8
9// Top-level directories: a URI ending in one of them is a directory, not a source.
10const DIRS = new Set(["resources", "user", "agent", "session", "memories", "skills", "peers"]);
11
12// A URI that names something an answer could draw on, not a scope or directory.
13export function isSource(uri: string): boolean {
14  if (uri.endsWith("/")) return false;
15  const parts = uri.slice("viking://".length).split("/").filter(Boolean);
16  return parts.length >= 2 && !DIRS.has(parts.at(-1) ?? "");
17}
18
19// The source URIs a tool's output names, in order. The `ov` CLI wraps a long URI
20// onto the next line at the same indent; that continuation is joined back.
21export function urisIn(text: string): string[] {
22  const lines = text.split("\n");
23  const found: string[] = [];
24  for (let i = 0; i < lines.length; i++) {
25    const line = lines[i] ?? "";
26    const whole = /^(\s*)(viking:\/\/\S+)\s*$/.exec(line);
27    const next = lines[i + 1] ?? "";
28    if (whole && !/\.\w{1,5}$/.test(whole[2] ?? "")) {
29      const tail = new RegExp(`^${whole[1]}(\\S+\\.\\w{1,5})\\s*$`).exec(next);
30      if (tail && !/^[#*-]/.test(tail[1] ?? "")) {
31        found.push(`${whole[2]}${tail[1]}`);
32        i++;
33        continue;
34      }
35    }
36    found.push(...(line.match(URI) ?? []));
37  }
38  return [...new Set(found)].filter(isSource);
39}
40
41export type Recalled = { uri: string; score: number };
42
43// What auto-recall injected for a prompt: <memory uri score> items, or the
44// digest form's "- summary 来源：viking://..." lines.
45export function parseRecall(text: string): Recalled[] {
46  const items: Recalled[] = [];
47  for (const m of text.matchAll(/<memory\s([^>]*?)\/?>/g)) {
48    const uri = /uri="([^"]+)"/.exec(m[1] ?? "")?.[1];
49    if (uri) items.push({ uri, score: Number(/score="([\d.]+)"/.exec(m[1] ?? "")?.[1] ?? 0) });
50  }
51  if (!items.length) {
52    for (const line of text.split("\n")) {
53      const uri = /^\s*-/.test(line) ? line.match(URI)?.[0] : undefined;
54      if (uri) items.push({ uri, score: 0 });
55    }
56  }
57  const seen = new Set<string>();
58  return items.filter((it) => isSource(it.uri) && !seen.has(it.uri) && !!seen.add(it.uri));
59}
60
61// Secrets never reach storage: JWT-like tokens, Bearer headers, sk- keys, key=value.
62export function redact(text: string): string {
63  return text
64    .replace(/[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{40,}/g, "[REDACTED]")
65    .replace(/Bearer\s+[A-Za-z0-9._~+/-]{16,}/gi, "Bearer [REDACTED]")
66    .replace(/sk-[A-Za-z0-9_-]{20,}/g, "[REDACTED]")
67    .replace(
68      /((?:api[_-]?key|token|secret|password|authorization)["']?\s*[:=]\s*["']?|--(?:api-key|token|password)[=\s]+)[^\s"',;&|]+/gi,
69      "$1[REDACTED]",
70    );
71}
72
73const MCP_TOOL = /^mcp__.*openviking.*__(\w+)$/;
74const MCP_SEARCH = new Set(["search", "find", "grep", "glob", "list", "tree"]);
75
76// `ov` CLI subcommands that open the files they name, and those that list matches.
77const CLI_READ = new Set(["read", "cat", "abstract", "overview"]);
78const CLI_SEARCH = new Set(["find", "search", "grep", "glob", "ls", "tree"]);
79
80// One `ov` / `openviking` invocation at the start of a command or after ; & | (
81const CLI_CALL = /(?:^|[;&|(]\s*)(?:\S+=\S+\s+)*(?:ov|openviking)\s+([a-z][\w-]*)([^;&|\n]*)/g;
82
83// How one tool call reads OpenViking: the URIs it opens in full, and what it
84// searched for. Null when the call is not an OpenViking lookup (writes and
85// status checks included). A shell command itself is never kept.
86export function classifyCall(
87  tool: string,
88  input: Record<string, unknown>,
89): { opened: string[]; query: string | null } | null {
90  const mcp = MCP_TOOL.exec(tool)?.[1];
91  if (mcp === "read") {
92    const raw = Array.isArray(input.uris)
93      ? input.uris.join(" ")
94      : String(input.uri ?? input.uris ?? "");
95    return { opened: (raw.match(URI) ?? []).filter(isSource), query: null };
96  }
97  if (mcp && MCP_SEARCH.has(mcp)) {
98    const q = input.query ?? input.pattern ?? input.uri ?? input.path ?? "";
99    return { opened: [], query: redact(String(q)).slice(0, 80) };
100  }
101  if (tool !== "Bash" || typeof input.command !== "string") return null;
102  const opened: string[] = [];
103  let query: string | null = null;
104  for (const m of input.command.matchAll(CLI_CALL)) {
105    const sub = m[1] ?? "";
106    const rest = m[2] ?? "";
107    if (CLI_READ.has(sub)) opened.push(...(rest.match(URI) ?? []).filter(isSource));
108    else if (CLI_SEARCH.has(sub) && query === null) {
109      const quoted = /["']([^"']+)["']/.exec(rest)?.[1];
110      const words = rest.replace(/\s-{1,2}\w[\w-]*(?:[=\s]\S+)?/g, " ").replace(/\s\d?>.*$/, "");
111      query = redact((quoted ?? words).trim()).slice(0, 80);
112    }
113  }
114  return opened.length || query !== null ? { opened: [...new Set(opened)], query } : null;
115}
116
117export type Group = "prefs" | "history" | "work" | "docs" | "skill";
118
119// What a source is to the person, from where it lives.
120export function groupOf(uri: string): Group {
121  if (/^viking:\/\/user\/[^/]+\/memories\/(preferences|profile|identity|soul)/.test(uri))
122    return "prefs";
123  if (/\/memories\/events\//.test(uri)) return "history";
124  if (/\/skills?\//.test(uri)) return "skill";
125  if (/^viking:\/\/user\/[^/]+\/(memories|peers)\//.test(uri)) return "work";
126  return "docs";
127}
128
129export const ICON: Record<Group, string> = {
130  prefs: "★",
131  history: "◷",
132  work: "◆",
133  docs: "▤",
134  skill: "⚙",
135};
136
137const NOUN: Record<Group, [string, string]> = {
138  prefs: ["preference", "preferences"],
139  history: ["past event", "past events"],
140  work: ["work memory", "work memories"],
141  docs: ["team doc", "team docs"],
142  skill: ["skill", "skills"],
143};
144
145const plural = (n: number, [one, many]: [string, string]) => `${n} ${n === 1 ? one : many}`;
146
147// URIs can hold a literal "%" (a title like "50% off"), which decodeURIComponent rejects.
148function decodeUri(uri: string): string {
149  try {
150    return decodeURIComponent(uri);
151  } catch {
152    return uri;
153  }
154}
155
156// A short name for a source: its file name, with the date of a dated event.
157export function titleOf(uri: string): string {
158  const parts = decodeUri(uri).split("/").filter(Boolean);
159  let name = (parts.at(-1) ?? uri).replace(/\.md$/, "");
160  if (/^(\.|summary$|index$|prompts$)/i.test(name)) name = `${parts.at(-2) ?? ""}/${name}`;
161  const d = /\/(\d{4})\/(\d{2})\/(\d{2})\//.exec(uri);
162  return d ? `${Number(d[2])}/${Number(d[3])} ${name}` : name;
163}
164
165export type Row = { uri: string; from: "recall" | "lookup"; score: number; isOpened: boolean };
166
167// What one answer consulted: auto-recall's items and what Claude's own reads and
168// searches returned, files Claude opened first, then by recall score.
169export function consulted(turn: Turn) {
170  const opened = new Set(turn.lookups.flatMap((l: Lookup) => (l.isError ? [] : l.opened)));
171  const rows = new Map<string, Row>();
172  for (const it of turn.recalled)
173    rows.set(it.uri, { uri: it.uri, from: "recall", score: it.score, isOpened: false });
174  for (const l of turn.lookups) {
175    if (l.isError) continue;
176    for (const uri of [...l.opened, ...l.found]) {
177      if (!rows.has(uri)) rows.set(uri, { uri, from: "lookup", score: 0, isOpened: false });
178    }
179  }
180  for (const r of rows.values()) r.isOpened = opened.has(r.uri);
181  const list = [...rows.values()].sort(
182    (a, b) => Number(b.isOpened) - Number(a.isOpened) || b.score - a.score,
183  );
184  const byGroup: Record<Group, number> = { prefs: 0, history: 0, work: 0, docs: 0, skill: 0 };
185  for (const r of list) byGroup[groupOf(r.uri)] += 1;
186  return { rows: list, byGroup, readInFull: list.filter((r) => r.isOpened).length };
187}
188
189// The collapsed card: "OV · 8 sources · 4 past events · 3 work memories · 1 read in full".
190export function summaryLine(c: ReturnType<typeof consulted>): string {
191  const groups = (Object.keys(NOUN) as Group[])
192    .filter((g) => c.byGroup[g] > 0)
193    .map((g) => plural(c.byGroup[g], NOUN[g]));
194  return [
195    "OV",
196    plural(c.rows.length, ["source", "sources"]),
197    ...groups,
198    c.readInFull ? `${c.readInFull} read in full` : "",
199  ]
200    .filter(Boolean)
201    .join(" · ");
202}
203
204// A short fingerprint of a reply's text, so the card can find its reply where the
205// surface names rows by API message id (the desktop) without storing the text.
206export function hashText(s: string): string {
207  let h = 5381;
208  const t = s.trim();
209  for (let i = 0; i < t.length; i++) h = ((h << 5) + h + t.charCodeAt(i)) | 0;
210  return `${t.length}:${(h >>> 0).toString(36)}`;
211}
212

1// One OpenViking lookup Claude made while answering. opened: files it read in
2// full; found: what a search returned; query: what it searched for (null for a read).
3export type Lookup = {
4  id: string;
5  query: string | null;
6  opened: string[];
7  found: string[];
8  isError: boolean;
9};
10
11// One answer: what auto-recall injected for its prompt, and Claude's own lookups.
12export type Turn = {
13  n: number;
14  recalled: { uri: string; score: number }[];
15  lookups: Lookup[];
16};
17
18// The transcript row an answer's card is drawn under: its row id (the terminal's
19// requestId) and a hash of its text, since the desktop names rows by API message id.
20export type Reply = { id: string; n: number; text?: string };
21
22declare module "claude-code" {
23  interface PluginState {
24    "openviking-memory": {
25      // this session's answers, oldest first (last 50)
26      turns: Turn[];
27      replies: Reply[];
28      // answers whose card is expanded
29      expanded: number[];
30    };
31  }
32}
33