omp-memory-atlas 0.1.0

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "omp-memory-atlas",
+  "version": "0.1.0",
+  "description": "On-demand project knowledge maps for Oh My Pi, backed by automatically curated mental models.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": ">=17.2.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,178 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { computeBankScope } from "@oh-my-pi/pi-coding-agent/hindsight/bank";
+import {
+	createHindsightClient,
+	type HindsightApi,
+	type MentalModelSummary,
+} from "@oh-my-pi/pi-coding-agent/hindsight/client";
+import { isHindsightConfigured, loadHindsightConfig } from "@oh-my-pi/pi-coding-agent/hindsight/config";
+import { resolveSeedsForScope } from "@oh-my-pi/pi-coding-agent/hindsight/mental-models";
+
+const CATALOGUE_TTL_MS = 5 * 60 * 1000;
+
+type ProjectMemory = {
+	client: HindsightApi;
+	bankId: string;
+	projectTags: string[];
+	coreModelIds: Set<string>;
+};
+
+type CachedCatalogue = {
+	expiresAt: number;
+	models: MentalModelSummary[];
+};
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+function projectMemory(cwd: string): ProjectMemory {
+	const config = loadHindsightConfig(settings);
+	if (!isHindsightConfigured(config)) {
+		throw new Error("Hindsight is not configured.");
+	}
+	const scope = computeBankScope(config, cwd);
+	return {
+		client: createHindsightClient(config),
+		bankId: scope.bankId,
+		projectTags: scope.retainTags ?? [],
+		coreModelIds: new Set(
+			resolveSeedsForScope(scope, config.scoping).flatMap((seed) => [seed.id, ...(seed.legacyIds ?? [])]),
+		),
+	};
+}
+
+function isProjectModel(model: MentalModelSummary, projectTags: string[]): boolean {
+	if (projectTags.length === 0) return true;
+	if (!model.tags || model.tags.length === 0) return true;
+	return model.tags.some((tag) => projectTags.includes(tag));
+}
+
+function areaModels(models: MentalModelSummary[], projectTags: string[], coreModelIds: Set<string>): MentalModelSummary[] {
+	return models
+		.filter((model) => !coreModelIds.has(model.id))
+		.filter((model) => isProjectModel(model, projectTags))
+		.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function modelDescription(model: MentalModelSummary): string {
+	const heading = model.content?.match(/^#{1,6}\s+(.+)$/m)?.[1]?.trim();
+	if (heading) return heading;
+	const sourceQuery = model.source_query?.replace(/\s+/g, " ").trim();
+	if (sourceQuery) return sourceQuery;
+	const opening = model.content?.replace(/\s+/g, " ").trim();
+	return opening || "No description available";
+}
+
+function catalogueLine(model: MentalModelSummary): string {
+	const scope = modelDescription(model);
+	const description = scope.length > 180 ? `${scope.slice(0, 177)}...` : scope;
+	return `- ${model.name} [${model.id}]: ${description}`;
+}
+
+function catalogueBlock(models: MentalModelSummary[]): string {
+	const entries = models.length === 0 ? "- No project memory areas exist yet." : models.map(catalogueLine).join("\n");
+	return `## Project memory catalogue\n\nThis catalogue contains historical knowledge areas for this project. Load a relevant area with \`get_project_mental_model\` before relying on historical assumptions. Create an area with \`create_project_mental_model\` when durable project history does not fit an existing area.\n\n${entries}`;
+}
+
+export default function memoryAtlas(pi: ExtensionAPI) {
+	const { z } = pi.zod;
+	let catalogue: CachedCatalogue | undefined;
+	let sessionCatalogueBlock: string | undefined;
+
+	async function loadCatalogue(cwd: string, force = false): Promise<MentalModelSummary[]> {
+		if (!force && catalogue && catalogue.expiresAt > Date.now()) return catalogue.models;
+		const memory = projectMemory(cwd);
+		const response = await memory.client.listMentalModels(memory.bankId, { detail: "content" });
+		const models = areaModels(response.items, memory.projectTags, memory.coreModelIds);
+		catalogue = { expiresAt: Date.now() + CATALOGUE_TTL_MS, models };
+		return models;
+	}
+
+	async function resolveModel(cwd: string, nameOrId: string): Promise<{ memory: ProjectMemory; model: MentalModelSummary }> {
+		const memory = projectMemory(cwd);
+		const models = await loadCatalogue(cwd);
+		const model = models.find((candidate) => candidate.id === nameOrId || candidate.name === nameOrId);
+		if (!model) throw new Error(`Unknown project mental model: ${nameOrId}`);
+		return { memory, model };
+	}
+
+	for (const event of ["session_start", "session_switch", "session_branch", "session_tree"] as const) {
+		pi.on(event, () => {
+			sessionCatalogueBlock = undefined;
+		});
+	}
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!sessionCatalogueBlock) {
+			sessionCatalogueBlock = catalogueBlock(await loadCatalogue(ctx.cwd));
+		}
+		return { systemPrompt: [...event.systemPrompt, sessionCatalogueBlock] };
+	});
+
+	pi.registerTool({
+		name: "get_project_mental_model",
+		label: "Get Project Mental Model",
+		description: "Load the full Hindsight mental model for an area shown in the project memory catalogue.",
+		parameters: z.object({ area: z.string().min(1) }),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const { memory, model } = await resolveModel(ctx.cwd, params.area);
+			const full = await memory.client.getMentalModel(memory.bankId, model.id, { detail: "content", signal });
+			if (!full) throw new Error(`Project mental model disappeared: ${model.id}`);
+			return textResult(full.content?.trim() || "Mental model exists but has no generated content yet.", {
+				id: full.id,
+				name: full.name,
+				lastRefreshedAt: full.last_refreshed_at,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "create_project_mental_model",
+		label: "Create Project Mental Model",
+		description: "Create a project-scoped Hindsight mental model that refreshes automatically after memory consolidation.",
+		parameters: z.object({
+			name: z.string().min(1),
+			sourceQuery: z.string().min(1),
+			maxTokens: z.number().int().min(256).max(8000).default(2000),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const memory = projectMemory(ctx.cwd);
+			const existing = await loadCatalogue(ctx.cwd, true);
+			if (existing.some((model) => model.name === params.name || model.id === params.name)) {
+				throw new Error(`Project mental model already exists: ${params.name}`);
+			}
+			const result = await memory.client.createMentalModel(memory.bankId, params.name, params.sourceQuery, {
+				id: params.name,
+				tags: memory.projectTags,
+				maxTokens: params.maxTokens,
+				trigger: { mode: "delta", refresh_after_consolidation: true },
+				signal,
+			});
+			const updatedModels = [
+				...existing,
+				{
+					id: params.name,
+					bank_id: memory.bankId,
+					name: params.name,
+					tags: memory.projectTags,
+					source_query: params.sourceQuery,
+				},
+			].sort((left, right) => left.name.localeCompare(right.name));
+			pi.sendMessage(
+				{
+					customType: "project-memory-catalogue-update",
+					content: `## Updated project memory catalogue\n\n${catalogueBlock(updatedModels)}`,
+					display: false,
+				},
+				{ deliverAs: "nextTurn" },
+			);
+			catalogue = undefined;
+			return textResult(`Queued project mental model creation: ${params.name}`, {
+				name: params.name,
+				operationId: result.operation_id,
+			});
+		},
+	});
+}