repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/memory/index.ts
Rawimport type {
ExtensionAPI,
ExtensionContext,
} from "@earendil-works/pi-coding-agent";
import { keyHint } from "@earendil-works/pi-coding-agent";
import { stripTerminalSequences, Text } from "@earendil-works/pi-tui";
import { type Static, Type } from "typebox";
import { Value } from "typebox/value";
import { closeDebug, dbg } from "./src/debug.ts";
import type { RunOptions } from "./src/exec.ts";
import { pruneSpills, runSql, type SqlOutcome } from "./src/exec.ts";
import {
DEFAULT_TIMEOUT_MS,
MAX_SQL_LENGTH,
MAX_TIMEOUT_MS,
SCHEMA_VERSION,
} from "./src/guide.ts";
import { resolveSetting } from "./src/pi-ext-settings.ts";
import { DATABASE_SETTING, defaultDatabasePath } from "./src/settings.ts";
import type { MemoryStore } from "./src/store.ts";
const parameters = Type.Object(
{
sql: Type.String({
minLength: 1,
maxLength: MAX_SQL_LENGTH,
description:
"One SQLite statement, or several separated by ';'. Full DDL/DML.",
}),
params: Type.Optional(
Type.Array(
Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]),
{
maxItems: 100,
description: "Positional bind values for a single-statement call.",
},
),
),
readonly: Type.Optional(
Type.Boolean({
description:
"Enforce a read-only connection. Writes fail cleanly instead of mutating.",
}),
),
timeoutMs: Type.Optional(
Type.Integer({
minimum: 1000,
maximum: MAX_TIMEOUT_MS,
description: `Kill statements that run longer than this. Default ${DEFAULT_TIMEOUT_MS}.`,
}),
),
},
{ additionalProperties: false },
);
const jsonValue = Type.Union([
Type.String(),
Type.Number(),
Type.Boolean(),
Type.Null(),
]);
const outputSchema = Type.Object({
status: Type.String(),
rowCount: Type.Integer(),
columns: Type.Array(Type.String()),
rows: Type.Array(Type.Array(jsonValue)),
truncated: Type.Boolean(),
spillPath: Type.Union([Type.String(), Type.Null()]),
changes: Type.Integer(),
durationMs: Type.Integer(),
tablesTouched: Type.Array(Type.String()),
schemaChanged: Type.Boolean(),
journalSeq: Type.Integer(),
});
type MemoryArgs = Static<typeof parameters>;
function validateArgs(value: unknown): MemoryArgs {
if (!value || typeof value !== "object" || Array.isArray(value))
throw new Error("memory: expected object arguments with an 'sql' string");
if (!Value.Check(parameters, value)) {
const error = Value.Errors(parameters, value)[0];
const field =
error && "path" in error && typeof error.path === "string"
? error.path.split("/")[1]
: "arguments";
throw new Error(
`memory: invalid field ${field}: ${error?.message ?? "schema mismatch"}`,
);
}
return value;
}
function statusLine(outcome: SqlOutcome): string {
if (outcome.schemaChanged)
return `schema changed (${outcome.tablesTouched.join(", ") || "no table attributed"}); document it in _schema_docs`;
if (outcome.changes > 0) return `${outcome.changes} row(s) written`;
if (outcome.truncated)
return `${outcome.rowCount} rows; first ${outcome.rows.length} inline, full set spilled to a temp file`;
return `${outcome.rowCount} row(s)`;
}
export default function memoryExtension(pi: ExtensionAPI): void {
let store: MemoryStore | undefined;
let opening: Promise<MemoryStore> | undefined;
let generation = 0;
async function database(ctx: ExtensionContext): Promise<MemoryStore> {
if (store) return store;
if (opening) return opening;
const setting = resolveSetting(pi, ctx, DATABASE_SETTING);
if (!setting.ok) throw new Error(setting.error);
const path =
setting.source === "default" ? defaultDatabasePath() : setting.value;
const token = generation;
opening = (async () => {
const { MemoryStore } = await import("./src/store.ts");
const next = await MemoryStore.open(path);
if (generation !== token) {
next.close();
throw new Error("Memory session closed during open");
}
store = next;
dbg?.("database.open", { outcome: "ok" });
return next;
})();
try {
return await opening;
} catch (error) {
dbg?.("database.open", {
outcome:
error instanceof Error && error.name === "V1DatabaseError"
? "refused"
: "error",
});
throw error;
} finally {
opening = undefined;
}
}
pi.registerTool({
name: "memory",
annotations: { readOnlyHint: false },
label: "Memory",
description: `Your knowledge store: one local SQLite database whose schema you own and evolve with full SQL. Start by SELECT * FROM _guide (conventions) and _schema_docs (what each table means); INSERT a row into _schema_docs whenever you CREATE or ALTER a user table. Suggested shape: facts(entity, attribute, value, observed_at, source), append-only events(kind, subject, payload, occurred_at), edges(from_id, kind, to_id). Context is data: project/topic columns, not separate tables. readonly=true enforces a read-only connection. Reserved: _journal/_stats_samples/_health_runs are readable but not writable; ATTACH, VACUUM INTO, and PRAGMA application_id/user_version/journal_mode are blocked (single-file audit boundary). Results over ${50} rows are truncated with a temp NDJSON spill path; statements are killed at timeoutMs (default ${DEFAULT_TIMEOUT_MS / 1000}s). Never store secrets; keep transactions short.`,
parameters,
outputSchema,
async execute(_id, args, signal, _onUpdate, ctx) {
if (signal?.aborted) throw new Error("Memory operation aborted");
const parsed = validateArgs(args);
const db = await database(ctx);
if (signal?.aborted) throw new Error("Memory operation aborted");
let outcome: SqlOutcome;
try {
const options: RunOptions = {
actor: "agent",
readonly: parsed.readonly ?? false,
params: parsed.params ?? [],
};
if (parsed.timeoutMs !== undefined)
options.timeoutMs = parsed.timeoutMs;
outcome = await runSql(db, parsed.sql, options);
} catch (error) {
dbg?.("tool.call", {
outcome: /was killed/u.test(
error instanceof Error ? error.message : "",
)
? "timeout"
: /blocked|reserved/u.test(
error instanceof Error ? error.message : "",
)
? "denied"
: "error",
readonly: parsed.readonly ?? false,
durationMs: 0,
rowsReturned: 0,
schemaChanged: false,
});
throw error;
}
dbg?.("tool.call", {
outcome: "ok",
readonly: parsed.readonly ?? false,
rowsReturned: outcome.rowCount,
durationMs: outcome.durationMs,
schemaChanged: outcome.schemaChanged,
});
const data = {
status: statusLine(outcome),
rowCount: outcome.rowCount,
columns: outcome.columns,
rows: outcome.rows,
truncated: outcome.truncated,
spillPath: outcome.spillPath,
changes: outcome.changes,
durationMs: outcome.durationMs,
tablesTouched: outcome.tablesTouched,
schemaChanged: outcome.schemaChanged,
journalSeq: outcome.journalSeq,
};
return {
content: [{ type: "text", text: JSON.stringify(data) }],
details: data,
structuredContent: data,
};
},
renderCall(args, theme, context) {
const summary =
typeof args?.sql === "string"
? stripTerminalSequences(args.sql)
.replaceAll(/\s+/gu, " ")
.slice(0, 60)
: "…";
const title = theme.fg("toolTitle", `memory ${summary}`);
return new Text(
context.expanded
? `${title}\n${stripTerminalSequences(JSON.stringify(args) ?? "")}`
: `${title} · ${(context.keyHint ?? keyHint)("app.tools.expand", "to expand")}`,
0,
0,
);
},
renderResult(result, { expanded }, theme, context) {
const details = result.details;
const status =
details && typeof details === "object" && "status" in details
? String(details.status).slice(0, 120)
: "result";
const body = expanded
? result.content
.filter((c) => c.type === "text")
.map((c) => c.text)
.join("\n")
: `${status} · ${(context.keyHint ?? keyHint)("app.tools.expand", "to expand")}`;
return new Text(
theme.fg("toolOutput", stripTerminalSequences(body)),
0,
0,
);
},
});
pi.registerCommand("memory", {
description: `Browse, query, and audit the agent knowledge store (SQLite v${SCHEMA_VERSION})`,
async handler(args, ctx) {
if (ctx.mode !== "tui") {
ctx.ui.notify(
"The memory viewer requires interactive TUI; the memory tool works headlessly.",
"warning",
);
return;
}
dbg?.("viewer.open", { outcome: "ok" });
try {
const db = await database(ctx);
const { viewer } = await import("./src/viewer.ts");
await viewer(pi, db, ctx, args.trim());
} catch (error) {
ctx.ui.notify(
error instanceof Error ? error.message : "Memory viewer failed",
"error",
);
}
},
});
pi.on("session_start", (_event, _ctx) => {
dbg?.("session.start");
if (!store) return;
const db = store;
void Promise.resolve()
.then(() => {
pruneSpills(new Date());
db.pruneRetention(new Date());
})
.catch(() => {
// Retention is best effort; the journal simply grows this session.
});
});
pi.on("session_shutdown", () => {
generation++;
store?.close();
store = undefined;
dbg?.("session.shutdown");
closeDebug();
});
}