@alisio/plugin-memory 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Gutiérrez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @alisio/plugin-memory
+
+Engram-style persistent memory for [Alisio](https://github.com/GustavoGutierrez/alisio), shipped as a
+built-in plugin of the `alisio` CLI (disable with `--disable-plugin memory`). It depends only on
+`@alisio/sdk` and stores data through the SDK storage port (SQLite + FTS5 trigram, BM25 with recency).
+
+- Observations with title, type, What/Why/Where/Learned body, project or personal scope and topic-key upserts.
+- Tools: `memory_save`, `memory_search`, `memory_get`, `memory_context`, `memory_timeline`, `memory_pin`, `memory_forget`.
+- Memory-aware compaction: extracts observations in the same summarizer call, archives the checkpoint
+  and injects budgeted recall; session summaries on exit; `/memory` command.
+
+Configuration lives under `builtinPlugins.memory`. Docs: [Memory plugin](https://gustavogutierrez.github.io/alisio/memory).
+
+Maintainer: Gustavo Gutiérrez · License: MIT

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/** Options under `builtinPlugins.memory` in the Alisio configuration. */
+export declare const memoryConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    dbPath: z.ZodOptional<z.ZodString>;
+    injectBudgetTokens: z.ZodDefault<z.ZodNumber>;
+    recallLimit: z.ZodDefault<z.ZodNumber>;
+    autoSummary: z.ZodDefault<z.ZodBoolean>;
+    defaultScope: z.ZodDefault<z.ZodEnum<{
+        personal: "personal";
+        project: "project";
+    }>>;
+}, z.core.$strict>;
+export type MemoryConfig = z.infer<typeof memoryConfigSchema>;

package/dist/config.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/** Options under `builtinPlugins.memory` in the Alisio configuration. */
+export const memoryConfigSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    /** Defaults to `<state home>/memory.sqlite`; relative paths resolve from the config file. */
+    dbPath: z.string().min(1).optional(),
+    /** Token budget for injected memory context (session start and after compaction). */
+    injectBudgetTokens: z.number().int().min(100).max(20_000).default(1500),
+    /** Memories recalled after compaction. */
+    recallLimit: z.number().int().min(0).max(20).default(8),
+    /** Write a session summary via the provider on /clear, /exit or quit (TUI). */
+    autoSummary: z.boolean().default(true),
+    defaultScope: z.enum(["project", "personal"]).default("project"),
+})
+    .strict();

package/dist/format.d.ts

@@ -0,0 +1,54 @@
+import { type MemoryHit, type MemoryScope, type MemoryType } from "./types.ts";
+/** Same estimate as the core (~4 characters per token), kept local to stay decoupled. */
+export declare const estimateTokens: (text: string) => number;
+export interface Observation {
+    title: string;
+    type: MemoryType;
+    what: string;
+    why?: string;
+    where?: string;
+    learned?: string;
+    topicKey?: string;
+    scope?: MemoryScope;
+}
+export declare function formatObservation(o: Observation): string;
+export declare const redactPrivate: (text: string) => string;
+/** Lowercase kebab `family/description`, at most two levels (Engram convention). */
+export declare function normalizeTopicKey(key: string): string | undefined;
+export declare const suggestTopicKey: (type: MemoryType, title: string) => string;
+/**
+ * Quoted FTS5 terms (never raw user syntax). Terms need ≥3 characters because the index uses
+ * the trigram tokenizer.
+ */
+export declare function ftsQuery(text: string, mode?: "all" | "any"): string | undefined;
+/** BM25 (SQLite: lower is better) scaled by a 30-day recency decay and an access boost. */
+export declare function rankScore(bm25: number, updatedAt: number, accessCount: number, now: number): number;
+export declare const memoryLine: (m: MemoryHit, compact?: boolean) => string;
+/** Heading + optional body + memory rows, never exceeding `budgetTokens`. */
+export declare function renderInjection(input: {
+    heading: string;
+    body?: string;
+    memories: MemoryHit[];
+    budgetTokens: number;
+}): string;
+/** Engram's mem_context layout (with ids for memory_get), budgeted; pinned rows always kept. */
+export declare function renderMemoryContext(data: {
+    project: string;
+    session?: string;
+    summary?: string;
+    prompts: string[];
+    pinned: MemoryHit[];
+    recent: MemoryHit[];
+}, budgetTokens: number): string;
+/** Validates model-extracted observations one by one; invalid items are dropped. */
+export declare function parseObservations(value: unknown): Observation[];
+export declare const OBSERVATIONS_FIELD = "array of durable observations worth remembering in future sessions:\n [{\"title\":\"verb + what\",\"type\":\"decision|bugfix|discovery|pattern|architecture|config|preference|learning\",\"what\":string,\"why\":string,\"where\":string,\"learned\":string,\"topic_key\":\"family/description\",\"scope\":\"project|personal\"}] ([] when nothing is durable)";
+export declare const COMPACTION_GUIDANCE = "For \"observations\": include only durable knowledge (decisions, fixed bugs, non-obvious\ndiscoveries, conventions, configuration, user preferences). Use lowercase kebab topic keys like\n\"decision/memory-location\" so later updates replace earlier ones. Use scope \"personal\" only for\nuser preferences that apply across projects.";
+export declare const MEMORY_PROTOCOL = "## Persistent memory (Alisio memory plugin)\nMemory tools write to Alisio's local memory store, never to the workspace.\nSave with memory_save right after: a bugfix, a decision, a non-obvious discovery, a config change,\nan established pattern or convention, or a learned user preference.\n- title: verb + what (e.g. \"Fixed lock leak in session store\"); type; scope (project by default,\n  personal for cross-project user preferences); topic_key \"family/description\" when the subject\n  may evolve (reuse it to update instead of duplicating).\n- content: what / why / where / learned.\nRecall: call memory_context first, then memory_search with 1-2 keywords, then memory_get for full\ndetails (memory_timeline shows neighbouring observations).\nMemory operations are bookkeeping, never the user-facing answer: always finish with the complete\nanswer to the user.";
+export declare const SESSION_SUMMARY_SYSTEM = "You write the end-of-session summary for a coding-agent session and extract durable memories.\nReply with ONLY a JSON object:\n{\"summary\":{\"goal\":string,\"instructions\":string[],\"discoveries\":string[],\"accomplished\":string[],\"nextSteps\":string[],\"relevantFiles\":string[]},\n \"observations\": array of durable observations worth remembering in future sessions:\n [{\"title\":\"verb + what\",\"type\":\"decision|bugfix|discovery|pattern|architecture|config|preference|learning\",\"what\":string,\"why\":string,\"where\":string,\"learned\":string,\"topic_key\":\"family/description\",\"scope\":\"project|personal\"}] ([] when nothing is durable)}\nKeep paths, commands and identifiers exact. Do not invent facts. Be concise.\nFor \"observations\": include only durable knowledge (decisions, fixed bugs, non-obvious\ndiscoveries, conventions, configuration, user preferences). Use lowercase kebab topic keys like\n\"decision/memory-location\" so later updates replace earlier ones. Use scope \"personal\" only for\nuser preferences that apply across projects.";
+/** Engram session summary sections; falls back to the raw text when JSON is invalid. */
+export declare function parseSessionSummary(raw: string): {
+    structured: boolean;
+    text: string;
+    observations: Observation[];
+};

package/dist/format.js

@@ -0,0 +1,240 @@
+/**
+ * Pure memory helpers: observation format, topic keys, FTS queries, ranking, budgeted context
+ * rendering and model-output parsing. No I/O here.
+ */
+import { z } from "zod";
+import { MEMORY_TYPES } from "./types.js";
+/** Same estimate as the core (~4 characters per token), kept local to stay decoupled. */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+export function formatObservation(o) {
+    return [
+        ["What", o.what],
+        ["Why", o.why],
+        ["Where", o.where],
+        ["Learned", o.learned],
+    ]
+        .filter(([, v]) => v?.trim())
+        .map(([k, v]) => `**${k}**: ${v?.trim()}`)
+        .join("\n");
+}
+export const redactPrivate = (text) => text.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]");
+const kebab = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** Lowercase kebab `family/description`, at most two levels (Engram convention). */
+export function normalizeTopicKey(key) {
+    const parts = key.split("/").map(kebab).filter(Boolean);
+    if (!parts.length)
+        return undefined;
+    const [family, ...rest] = parts;
+    const description = rest.join("-").slice(0, 80);
+    return description ? `${family}/${description}` : family;
+}
+const FAMILY = {
+    architecture: "architecture",
+    bugfix: "bug",
+    decision: "decision",
+    pattern: "pattern",
+    config: "config",
+    discovery: "discovery",
+    learning: "learning",
+    preference: "preference",
+};
+export const suggestTopicKey = (type, title) => normalizeTopicKey(`${FAMILY[type]}/${title}`) ?? FAMILY[type];
+/**
+ * Quoted FTS5 terms (never raw user syntax). Terms need ≥3 characters because the index uses
+ * the trigram tokenizer.
+ */
+export function ftsQuery(text, mode = "any") {
+    const tokens = [
+        ...new Set((text.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? []).filter((t) => t.length >= 3)),
+    ].slice(0, 16);
+    return tokens.length
+        ? tokens.map((t) => `"${t}"`).join(mode === "all" ? " AND " : " OR ")
+        : undefined;
+}
+const DAY = 86_400_000;
+/** BM25 (SQLite: lower is better) scaled by a 30-day recency decay and an access boost. */
+export function rankScore(bm25, updatedAt, accessCount, now) {
+    const relevance = Math.max(-bm25, 1e-9);
+    const age = Math.max(0, now - updatedAt) / DAY;
+    return relevance * (0.6 + 0.4 * Math.exp(-age / 30)) * (1 + 0.05 * Math.log1p(accessCount));
+}
+export const memoryLine = (m, compact = false) => `- #${m.id} [${m.type}] **${m.title}**${!compact && m.snippet ? `: ${m.snippet}` : ""}`;
+function clipLines(body, maxChars) {
+    if (body.length <= maxChars)
+        return body;
+    const marker = "\n[truncated]";
+    const room = maxChars - marker.length;
+    if (room <= 0)
+        return "";
+    let cut = body.slice(0, room);
+    const newline = cut.lastIndexOf("\n");
+    if (newline > room / 2)
+        cut = cut.slice(0, newline);
+    return `${cut}${marker}`;
+}
+/** Adds rows (full, else compact) while they fit in `room` characters. */
+function rows(memories, room) {
+    const out = [];
+    let used = 0;
+    for (const m of memories) {
+        const full = memoryLine(m), compact = memoryLine(m, true);
+        const line = used + full.length + 1 <= room ? full : compact;
+        if (used + line.length + 1 > room)
+            break;
+        out.push(line);
+        used += line.length + 1;
+    }
+    return out;
+}
+/** Heading + optional body + memory rows, never exceeding `budgetTokens`. */
+export function renderInjection(input) {
+    const limit = input.budgetTokens * 4;
+    const head = `[${input.heading}]\n`;
+    const memHeader = "\n## Relevant memories (call memory_get with an id for details)\n";
+    const reserve = input.memories.length ? Math.floor((limit - head.length) * 0.4) : 0;
+    const body = input.body?.trim()
+        ? clipLines(input.body.trim(), limit - head.length - reserve)
+        : "";
+    let out = `${head}${body}`;
+    const room = limit - out.length - memHeader.length;
+    const lines = room > 0 ? rows(input.memories, room) : [];
+    if (lines.length)
+        out += `${memHeader}${lines.join("\n")}`;
+    return out.slice(0, limit);
+}
+/** Engram's mem_context layout (with ids for memory_get), budgeted; pinned rows always kept. */
+export function renderMemoryContext(data, budgetTokens) {
+    const limit = budgetTokens * 4;
+    const header = "[Memory context from previous sessions (Alisio memory). Call memory_get with an id for details.]\n";
+    const session = `### Session\nproject ${data.project}${data.session ? ` · session ${data.session.slice(0, 8)}` : ""}\n`;
+    let remaining = limit - header.length - session.length;
+    let pinned = "";
+    if (data.pinned.length) {
+        const title = "### Pinned\n";
+        const lines = rows(data.pinned, Math.max(0, Math.floor(remaining * 0.4) - title.length));
+        const compact = rows(data.pinned.map((m) => ({ ...m, snippet: "" })), Math.max(0, remaining - title.length));
+        const chosen = lines.length === data.pinned.length ? lines : compact;
+        if (chosen.length)
+            pinned = `${title}${chosen.join("\n")}\n`;
+        remaining -= pinned.length;
+    }
+    const summary = data.summary?.trim()
+        ? `${clipLines(`### Last Session Summary\n${data.summary.trim()}`, Math.floor(remaining * 0.45))}\n`
+        : "";
+    remaining -= summary.length;
+    let prompts = "";
+    if (data.prompts.length) {
+        const room = Math.floor(remaining * 0.35);
+        const lines = [];
+        let used = "### Recent User Prompts\n".length;
+        for (const p of data.prompts.slice(0, 5)) {
+            const text = p.replace(/\s+/g, " ").trim();
+            const line = `- ${text.length > 200 ? `${text.slice(0, 200)}…` : text}`;
+            if (used + line.length + 1 > room)
+                continue;
+            lines.push(line);
+            used += line.length + 1;
+        }
+        if (lines.length)
+            prompts = `### Recent User Prompts\n${lines.join("\n")}\n`;
+        remaining -= prompts.length;
+    }
+    let recent = "";
+    const title = "### Recent Observations\n";
+    const pinnedIds = new Set(data.pinned.map((m) => m.id));
+    const lines = rows(data.recent.filter((m) => !pinnedIds.has(m.id)), remaining - title.length);
+    if (lines.length)
+        recent = `${title}${lines.join("\n")}\n`;
+    return `${header}${session}${summary}${prompts}${pinned}${recent}`.trimEnd().slice(0, limit);
+}
+const observationSchema = z.object({
+    title: z.string().trim().min(1).max(200),
+    type: z.enum(MEMORY_TYPES),
+    what: z.string().trim().min(1).max(4_000),
+    why: z.string().trim().max(2_000).optional(),
+    where: z.string().trim().max(1_000).optional(),
+    learned: z.string().trim().max(2_000).optional(),
+    topic_key: z.string().trim().max(120).optional(),
+    scope: z.enum(["project", "personal"]).optional(),
+});
+/** Validates model-extracted observations one by one; invalid items are dropped. */
+export function parseObservations(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value.slice(0, 20)) {
+        const parsed = observationSchema.safeParse(item);
+        if (!parsed.success)
+            continue;
+        const { topic_key, ...rest } = parsed.data;
+        const topicKey = topic_key ? normalizeTopicKey(topic_key) : undefined;
+        out.push(Object.fromEntries(Object.entries({ ...rest, ...(topicKey ? { topicKey } : {}) }).filter(([, v]) => v !== undefined && v !== "")));
+    }
+    return out;
+}
+export const OBSERVATIONS_FIELD = `array of durable observations worth remembering in future sessions:
+ [{"title":"verb + what","type":"decision|bugfix|discovery|pattern|architecture|config|preference|learning","what":string,"why":string,"where":string,"learned":string,"topic_key":"family/description","scope":"project|personal"}] ([] when nothing is durable)`;
+export const COMPACTION_GUIDANCE = `For "observations": include only durable knowledge (decisions, fixed bugs, non-obvious
+discoveries, conventions, configuration, user preferences). Use lowercase kebab topic keys like
+"decision/memory-location" so later updates replace earlier ones. Use scope "personal" only for
+user preferences that apply across projects.`;
+export const MEMORY_PROTOCOL = `## Persistent memory (Alisio memory plugin)
+Memory tools write to Alisio's local memory store, never to the workspace.
+Save with memory_save right after: a bugfix, a decision, a non-obvious discovery, a config change,
+an established pattern or convention, or a learned user preference.
+- title: verb + what (e.g. "Fixed lock leak in session store"); type; scope (project by default,
+  personal for cross-project user preferences); topic_key "family/description" when the subject
+  may evolve (reuse it to update instead of duplicating).
+- content: what / why / where / learned.
+Recall: call memory_context first, then memory_search with 1-2 keywords, then memory_get for full
+details (memory_timeline shows neighbouring observations).
+Memory operations are bookkeeping, never the user-facing answer: always finish with the complete
+answer to the user.`;
+const listSchema = z.array(z.string().trim().max(2_000)).max(40).default([]);
+const sessionSummarySchema = z.object({
+    summary: z.object({
+        goal: z.string().trim().min(1).max(2_000),
+        instructions: listSchema,
+        discoveries: listSchema,
+        accomplished: listSchema,
+        nextSteps: listSchema,
+        relevantFiles: listSchema,
+    }),
+    observations: z.array(z.unknown()).default([]),
+});
+export const SESSION_SUMMARY_SYSTEM = `You write the end-of-session summary for a coding-agent session and extract durable memories.
+Reply with ONLY a JSON object:
+{"summary":{"goal":string,"instructions":string[],"discoveries":string[],"accomplished":string[],"nextSteps":string[],"relevantFiles":string[]},
+ "observations": ${OBSERVATIONS_FIELD}}
+Keep paths, commands and identifiers exact. Do not invent facts. Be concise.
+${COMPACTION_GUIDANCE}`;
+const bullets = (items) => items.length ? items.map((i) => `- ${i}`).join("\n") : "- (none)";
+/** Engram session summary sections; falls back to the raw text when JSON is invalid. */
+export function parseSessionSummary(raw) {
+    try {
+        const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(raw)?.[1];
+        const value = JSON.parse(fenced ?? raw.slice(raw.indexOf("{"), raw.lastIndexOf("}") + 1));
+        const parsed = sessionSummarySchema.safeParse(value);
+        if (!parsed.success)
+            throw parsed.error;
+        const s = parsed.data.summary;
+        return {
+            structured: true,
+            observations: parseObservations(parsed.data.observations),
+            text: [
+                `## Goal\n${s.goal}`,
+                `## Instructions\n${bullets(s.instructions)}`,
+                `## Discoveries\n${bullets(s.discoveries)}`,
+                `## Accomplished\n${bullets(s.accomplished)}`,
+                `## Next Steps\n${bullets(s.nextSteps)}`,
+                `## Relevant Files\n${bullets(s.relevantFiles)}`,
+            ].join("\n\n"),
+        };
+    }
+    catch {
+        return { structured: false, text: raw.trim(), observations: [] };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { type Plugin } from "@alisio/sdk";
+export interface MemoryPluginContext {
+    workspace: string;
+    stateHome: string;
+    /** Directory of the configuration file, for relative `dbPath`. */
+    configDir: string;
+}
+export type ArchiveOutcome = "confirmed" | "failed" | "unknown";
+export declare function createMemoryPlugin(rawOptions: unknown, context: MemoryPluginContext): Plugin;

package/dist/index.js

@@ -0,0 +1,233 @@
+/**
+ * Built-in memory plugin (Engram-style). Everything memory-related lives in this directory;
+ * the core only exposes generic hooks. Disabled means: no store file, tools, prompt or hooks.
+ */
+import { isAbsolute, join, resolve } from "node:path";
+import { definePlugin } from "@alisio/sdk";
+import { memoryConfigSchema } from "./config.js";
+import { COMPACTION_GUIDANCE, formatObservation, MEMORY_PROTOCOL, memoryLine, OBSERVATIONS_FIELD, parseObservations, parseSessionSummary, renderInjection, SESSION_SUMMARY_SYSTEM, } from "./format.js";
+import { projectId, SQLiteMemoryStore } from "./store.js";
+import { memoryContextText, memoryTools } from "./tools.js";
+const userTexts = (messages) => messages.flatMap((m) => (m.role === "user" && !m.summary && m.text.trim() ? [m.text] : []));
+function transcript(messages, maxChars = 60_000) {
+    const lines = messages.map((m) => m.role === "user"
+        ? `${m.summary ? "CONTEXT" : "USER"}: ${m.text.slice(0, 4_000)}`
+        : m.role === "assistant"
+            ? [
+                m.text ? `ASSISTANT: ${m.text.slice(0, 4_000)}` : "",
+                ...m.calls.map((c) => `TOOL CALL ${c.id} ${c.name}: ${c.arguments.slice(0, 1_000)}`),
+            ]
+                .filter(Boolean)
+                .join("\n")
+            : `TOOL RESULT ${m.callId}: ${m.result.content
+                .map((c) => c.text)
+                .join("\n")
+                .slice(0, 1_500)}`);
+    const text = lines.join("\n");
+    return text.length > maxChars ? `[earlier messages omitted]\n${text.slice(-maxChars)}` : text;
+}
+export function createMemoryPlugin(rawOptions, context) {
+    const options = memoryConfigSchema.parse(rawOptions ?? {});
+    const dbPath = options.dbPath
+        ? isAbsolute(options.dbPath)
+            ? options.dbPath
+            : resolve(context.configDir, options.dbPath)
+        : join(context.stateHome, "memory.sqlite");
+    let store;
+    const stats = {
+        written: 0,
+        lastArchive: undefined,
+        lastSummary: "",
+    };
+    return definePlugin({
+        id: "memory",
+        name: "Memory",
+        description: "Persistent memory and memory-aware context compaction",
+        version: "0.1.0",
+        apiVersion: 1,
+        async setup(api) {
+            const project = await projectId(context.workspace);
+            const db = new SQLiteMemoryStore(api.storage.sqlite(dbPath));
+            store = db;
+            const deps = {
+                store: db,
+                project,
+                defaultScope: options.defaultScope,
+                budgetTokens: options.injectBudgetTokens,
+                onWrite: () => {
+                    stats.written++;
+                    refresh();
+                },
+            };
+            const refresh = () => {
+                const c = db.count(project);
+                api.ui.status("count", `mem ${c.project}${c.personal ? `+${c.personal}` : ""}`, [
+                    `project ${project}: ${c.project} project + ${c.personal} personal memories`,
+                    `${stats.written} writes in this process`,
+                    `last compaction archive: ${stats.lastArchive ?? "none"}`,
+                    ...(stats.lastSummary ? [`last session summary: ${stats.lastSummary}`] : []),
+                    `store: ${dbPath}`,
+                ].join(" · "));
+            };
+            const saveAll = (observations, session, source) => {
+                const counts = { created: 0, updated: 0, duplicate: 0 };
+                for (const o of observations) {
+                    const r = db.save({
+                        project,
+                        scope: o.scope ?? options.defaultScope,
+                        type: o.type,
+                        title: o.title,
+                        content: formatObservation(o),
+                        ...(o.topicKey ? { topicKey: o.topicKey } : {}),
+                        session,
+                        source,
+                    });
+                    counts[r.action]++;
+                }
+                return counts;
+            };
+            for (const tool of memoryTools(deps))
+                api.tools.register(tool);
+            api.context.register(async () => MEMORY_PROTOCOL);
+            api.compaction.register({
+                async beforeCompact() {
+                    return {
+                        instructions: COMPACTION_GUIDANCE,
+                        outputFields: { observations: OBSERVATIONS_FIELD },
+                    };
+                },
+                async afterCompact(result) {
+                    for (const text of userTexts(result.messages).slice(-10))
+                        db.recordPrompt(project, result.sessionId, text);
+                    const memories = saveAll(parseObservations(result.extracted.observations), result.sessionId, "compaction");
+                    // Deterministic archive of the checkpoint as the session summary, confirmed by readback.
+                    let archive;
+                    try {
+                        const stored = db.saveSummary(project, result.sessionId, result.checkpointText);
+                        archive = db.summaryOf(result.sessionId) === stored ? "confirmed" : "unknown";
+                    }
+                    catch {
+                        archive = "failed";
+                    }
+                    stats.lastArchive = archive;
+                    const query = result.checkpoint
+                        ? [result.checkpoint.goal, ...result.checkpoint.nextSteps].join(" ")
+                        : result.checkpointText.slice(0, 400);
+                    const recalled = options.recallLimit
+                        ? db.search(project, query, { mode: "any", limit: options.recallLimit })
+                        : [];
+                    refresh();
+                    return {
+                        ...(recalled.length
+                            ? {
+                                injectContext: renderInjection({
+                                    heading: "Recovered memory (Alisio memory plugin)",
+                                    memories: recalled,
+                                    budgetTokens: options.injectBudgetTokens,
+                                }),
+                            }
+                            : {}),
+                        report: {
+                            summary: `memory: +${memories.created} new, ${memories.updated} updated, ${memories.duplicate} duplicate · archive ${archive} · ${recalled.length} recalled`,
+                            archive,
+                            memories,
+                            recalled: recalled.length,
+                        },
+                    };
+                },
+            });
+            api.session.onStart(async (info) => {
+                refresh();
+                return memoryContextText(deps, info.sessionId);
+            });
+            api.session.onEnd(async (info) => {
+                const prompts = userTexts(info.messages);
+                const meaningful = prompts.length > 0 &&
+                    info.messages.some((m) => m.role === "assistant" && (m.text.trim() || m.calls.length));
+                if (!options.autoSummary || !meaningful)
+                    return;
+                for (const text of prompts.slice(-10))
+                    db.recordPrompt(project, info.sessionId, text);
+                try {
+                    const raw = await api.model.complete({
+                        system: SESSION_SUMMARY_SYSTEM,
+                        messages: [
+                            { role: "user", text: `<transcript>\n${transcript(info.messages)}\n</transcript>` },
+                        ],
+                        maxTokens: 2048,
+                        sessionId: info.sessionId,
+                        signal: info.signal,
+                    });
+                    const parsed = parseSessionSummary(raw);
+                    if (parsed.text)
+                        db.saveSummary(project, info.sessionId, parsed.text);
+                    const counts = saveAll(parsed.observations, info.sessionId, "session_summary");
+                    stats.lastSummary = `saved (${parsed.structured ? "structured" : "text-only"}, +${counts.created} memories)`;
+                }
+                catch (error) {
+                    stats.lastSummary = `failed (${error instanceof Error ? error.message : String(error)})`;
+                    throw error;
+                }
+                finally {
+                    refresh();
+                }
+            });
+            api.commands.register("memory", async (args) => {
+                const [verb = "", ...rest] = args.trim().split(/\s+/);
+                const target = Number(rest[0]);
+                const needsId = ["show", "forget", "pin", "unpin"].includes(verb);
+                if (needsId && !Number.isInteger(target))
+                    return `Usage: /memory ${verb} <id>`;
+                if (verb === "show") {
+                    const r = db.get(target, project);
+                    if (!r)
+                        return `Memory #${target} not found.`;
+                    return [
+                        `**#${r.id} [${r.type}] ${r.title}**`,
+                        "",
+                        `scope ${r.scope}${r.topicKey ? ` · topic \`${r.topicKey}\`` : ""} · revisions ${r.revisionCount} · duplicates ${r.duplicateCount}${r.pinned ? " · pinned" : ""}`,
+                        "",
+                        r.content,
+                    ].join("\n");
+                }
+                if (verb === "forget") {
+                    const ok = db.forget(target, project);
+                    if (ok)
+                        deps.onWrite();
+                    return ok ? `Forgot memory #${target}.` : `Memory #${target} not found.`;
+                }
+                if (verb === "pin" || verb === "unpin") {
+                    const ok = db.pin(target, project, verb === "pin");
+                    if (ok)
+                        deps.onWrite();
+                    return ok ? `Memory #${target} ${verb}ned.` : `Memory #${target} not found.`;
+                }
+                const c = db.count(project);
+                if (!args.trim()) {
+                    const recent = db.recent(project, 15);
+                    return [
+                        `**Memory** · ${c.project} project + ${c.personal} personal · project \`${project}\``,
+                        "",
+                        ...(recent.length ? recent.map((m) => memoryLine(m, true)) : ["No memories yet."]),
+                        "",
+                        "`/memory <query>` search · `/memory show|forget|pin|unpin <id>`",
+                    ].join("\n");
+                }
+                let hits = db.search(project, args, { limit: 15 });
+                if (!hits.length)
+                    hits = db.search(project, args, { limit: 15, mode: "any" });
+                return hits.length
+                    ? [`**Memory search:** ${args}`, "", ...hits.map((m) => memoryLine(m))].join("\n")
+                    : `No memories match "${args}".`;
+            }, {
+                description: "List, search, show, pin or forget memories",
+                argumentHint: "[query | show <id> | forget <id> | pin <id>]",
+            });
+            refresh();
+        },
+        dispose() {
+            store?.close();
+            store = undefined;
+        },
+    });
+}

package/dist/store.d.ts

@@ -0,0 +1,42 @@
+import type { SqlDatabase } from "@alisio/sdk";
+import type { MemoryHit, MemoryInput, MemoryRecord, MemoryStore, SaveAction, SearchOptions, SessionSummary } from "./types.ts";
+export declare const MAX_OBSERVATION_LENGTH = 50000;
+/** Stable project id: `<basename>-<sha256(realpath)[0:8]>` of the git root or cwd. */
+export declare function projectId(path: string): Promise<string>;
+export declare class SQLiteMemoryStore implements MemoryStore {
+    readonly db: SqlDatabase;
+    private now;
+    private dedupWindowMs;
+    /** `db` comes from the SDK storage port (`api.storage.sqlite`) or any compatible adapter. */
+    constructor(db: SqlDatabase, options?: {
+        now?: () => number;
+        dedupWindowMs?: number;
+    });
+    private migrate;
+    save(input: MemoryInput): {
+        id: number;
+        action: SaveAction;
+    };
+    search(project: string, query: string, options?: SearchOptions): MemoryHit[];
+    recent(project: string, limit?: number): MemoryHit[];
+    pinned(project: string, limit?: number): MemoryHit[];
+    get(id: number, project: string): MemoryRecord | undefined;
+    timeline(id: number, project: string, before?: number, after?: number): MemoryHit[];
+    pin(id: number, project: string, pinned: boolean): boolean;
+    forget(id: number, project: string, hard?: boolean): boolean;
+    count(project: string): {
+        project: number;
+        personal: number;
+    };
+    recordPrompt(project: string, session: string, content: string): void;
+    recentPrompts(project: string, limit?: number): {
+        session: string;
+        content: string;
+        createdAt: number;
+    }[];
+    saveSummary(project: string, session: string, content: string): string;
+    lastSummary(project: string): SessionSummary | undefined;
+    /** Session summary of one session, used to confirm an archive write. */
+    summaryOf(session: string): string | undefined;
+    close(): void;
+}

package/dist/store.js

@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { basename } from "node:path";
+import { ftsQuery, normalizeTopicKey, rankScore, redactPrivate } from "./format.js";
+/** Memory schema versions live at 100+ so the file can be shared with the session store. */
+const MEMORY_SCHEMA_VERSION = 100;
+export const MAX_OBSERVATION_LENGTH = 50_000;
+const TRUNCATED = "... [truncated]";
+const SNIPPET = 300;
+/** Stable project id: `<basename>-<sha256(realpath)[0:8]>` of the git root or cwd. */
+export async function projectId(path) {
+    const real = await realpath(path);
+    const name = basename(real).replace(/[^\w.-]/g, "-") || "root";
+    return `${name}-${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
+}
+const normalize = (text) => text.toLowerCase().replace(/\s+/g, " ").trim();
+const cap = (text, max) => text.length > max ? `${text.slice(0, max - TRUNCATED.length)}${TRUNCATED}` : text;
+const hit = (r) => {
+    const flat = r.content.replace(/\s+/g, " ").trim();
+    return {
+        id: r.id,
+        type: r.type,
+        title: r.title,
+        snippet: flat.length > SNIPPET ? `${flat.slice(0, SNIPPET)}…` : flat,
+        scope: r.scope,
+        ...(r.topic_key ? { topicKey: r.topic_key } : {}),
+        updatedAt: r.updated_at,
+        ...(r.pinned ? { pinned: true } : {}),
+    };
+};
+const VISIBLE = "o.deleted_at IS NULL AND (o.project=? OR o.scope='personal')";
+export class SQLiteMemoryStore {
+    db;
+    now;
+    dedupWindowMs;
+    /** `db` comes from the SDK storage port (`api.storage.sqlite`) or any compatible adapter. */
+    constructor(db, options = {}) {
+        this.now = options.now ?? Date.now;
+        this.dedupWindowMs = options.dedupWindowMs ?? 15 * 60_000;
+        this.db = db;
+        this.db.exec("PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; CREATE TABLE IF NOT EXISTS schema_migrations(version INTEGER PRIMARY KEY);");
+        this.migrate();
+    }
+    migrate() {
+        if (this.db.prepare("SELECT 1 FROM schema_migrations WHERE version=?").get(MEMORY_SCHEMA_VERSION))
+            return;
+        this.db.transaction(() => {
+            this.db.exec(`
+          CREATE TABLE IF NOT EXISTS observations(id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL,
+            tool_name TEXT, project TEXT NOT NULL, scope TEXT NOT NULL DEFAULT 'project',
+            topic_key TEXT, normalized_hash TEXT NOT NULL,
+            revision_count INTEGER NOT NULL DEFAULT 1, duplicate_count INTEGER NOT NULL DEFAULT 1,
+            last_seen_at INTEGER, pinned INTEGER NOT NULL DEFAULT 0,
+            access_count INTEGER NOT NULL DEFAULT 0, last_accessed_at INTEGER,
+            created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, deleted_at INTEGER);
+          CREATE INDEX IF NOT EXISTS observations_recent ON observations(project, deleted_at, updated_at DESC);
+          CREATE INDEX IF NOT EXISTS observations_topic ON observations(scope, topic_key, project) WHERE topic_key IS NOT NULL;
+          CREATE INDEX IF NOT EXISTS observations_hash ON observations(normalized_hash, project);
+          CREATE INDEX IF NOT EXISTS observations_session ON observations(session_id, created_at);
+          CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(title, content, tool_name, type,
+            project, topic_key, content='observations', content_rowid='id', tokenize='trigram');
+          CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+            INSERT INTO observations_fts(rowid,title,content,tool_name,type,project,topic_key)
+            VALUES(new.id,new.title,new.content,new.tool_name,new.type,new.project,new.topic_key); END;
+          CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+            INSERT INTO observations_fts(observations_fts,rowid,title,content,tool_name,type,project,topic_key)
+            VALUES('delete',old.id,old.title,old.content,old.tool_name,old.type,old.project,old.topic_key); END;
+          CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE OF title,content,tool_name,type,project,topic_key
+            ON observations BEGIN
+            INSERT INTO observations_fts(observations_fts,rowid,title,content,tool_name,type,project,topic_key)
+            VALUES('delete',old.id,old.title,old.content,old.tool_name,old.type,old.project,old.topic_key);
+            INSERT INTO observations_fts(rowid,title,content,tool_name,type,project,topic_key)
+            VALUES(new.id,new.title,new.content,new.tool_name,new.type,new.project,new.topic_key); END;
+          CREATE TABLE IF NOT EXISTS memory_sessions(id TEXT PRIMARY KEY, project TEXT NOT NULL,
+            directory TEXT, started_at INTEGER, ended_at INTEGER, summary TEXT);
+          CREATE INDEX IF NOT EXISTS memory_sessions_recent ON memory_sessions(project, ended_at DESC);
+          CREATE TABLE IF NOT EXISTS user_prompts(id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT,
+            content TEXT NOT NULL, project TEXT NOT NULL, created_at INTEGER NOT NULL);
+          CREATE INDEX IF NOT EXISTS user_prompts_recent ON user_prompts(project, created_at DESC);`);
+            this.db
+                .prepare("INSERT OR IGNORE INTO schema_migrations VALUES(?)")
+                .run(MEMORY_SCHEMA_VERSION);
+        });
+    }
+    save(input) {
+        const now = this.now();
+        const title = cap(redactPrivate(input.title).trim(), 200);
+        const content = cap(redactPrivate(input.content).trim(), MAX_OBSERVATION_LENGTH);
+        if (!title || !content)
+            throw new Error("Memory title and content are required");
+        const hash = createHash("sha256").update(normalize(content)).digest("hex");
+        const topicKey = input.topicKey ? normalizeTopicKey(input.topicKey) : undefined;
+        return this.db.transaction(() => {
+            const bump = (id) => {
+                this.db
+                    .prepare("UPDATE observations SET duplicate_count=duplicate_count+1, last_seen_at=?, updated_at=? WHERE id=?")
+                    .run(now, now, id);
+                return { id, action: "duplicate" };
+            };
+            if (topicKey) {
+                // Personal memories upsert across projects; project ones within the project.
+                const existing = this.db
+                    .prepare(`SELECT id, normalized_hash, title FROM observations WHERE deleted_at IS NULL AND scope=? AND topic_key=?
+               AND (scope='personal' OR project=?) ORDER BY updated_at DESC LIMIT 1`)
+                    .get(input.scope, topicKey, input.project);
+                if (existing) {
+                    if (existing.normalized_hash === hash && existing.title === title)
+                        return bump(existing.id);
+                    this.db
+                        .prepare(`UPDATE observations SET title=?, type=?, content=?, normalized_hash=?, session_id=?, tool_name=?,
+                 revision_count=revision_count+1, last_seen_at=?, updated_at=? WHERE id=?`)
+                        .run(title, input.type, content, hash, input.session ?? null, input.source ?? null, now, now, existing.id);
+                    return { id: existing.id, action: "updated" };
+                }
+            }
+            const duplicate = this.db
+                .prepare(`SELECT id FROM observations WHERE deleted_at IS NULL AND normalized_hash=? AND project=? AND scope=?
+             AND type=? AND title=? AND updated_at>=? ORDER BY updated_at DESC LIMIT 1`)
+                .get(hash, input.project, input.scope, input.type, title, now - this.dedupWindowMs);
+            if (duplicate)
+                return bump(duplicate.id);
+            const row = this.db
+                .prepare(`INSERT INTO observations(session_id,type,title,content,tool_name,project,scope,topic_key,normalized_hash,
+             last_seen_at,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?) RETURNING id`)
+                .get(input.session ?? null, input.type, title, content, input.source ?? null, input.project, input.scope, topicKey ?? null, hash, now, now, now);
+            return { id: row.id, action: "created" };
+        });
+    }
+    search(project, query, options = {}) {
+        const match = ftsQuery(query, options.mode ?? "all");
+        if (!match)
+            return [];
+        const limit = Math.min(Math.max(options.limit ?? 10, 1), 20);
+        const where = [
+            "observations_fts MATCH ?",
+            "o.deleted_at IS NULL",
+            ...(options.allProjects ? [] : ["(o.project=? OR o.scope='personal')"]),
+            ...(options.type ? ["o.type=?"] : []),
+            ...(options.scope ? ["o.scope=?"] : []),
+        ];
+        const params = [
+            match,
+            ...(options.allProjects ? [] : [project]),
+            ...(options.type ? [options.type] : []),
+            ...(options.scope ? [options.scope] : []),
+        ];
+        const rows = this.db
+            .prepare(`SELECT o.*, bm25(observations_fts, 5.0, 1.0, 0.5, 0.5, 0.2, 2.0) AS rank FROM observations_fts
+         JOIN observations o ON o.id = observations_fts.rowid WHERE ${where.join(" AND ")} ORDER BY rank LIMIT 100`)
+            .all(...params);
+        const now = this.now();
+        return rows
+            .map((r) => ({ r, score: rankScore(r.rank ?? 0, r.updated_at, r.access_count, now) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map(({ r }) => hit(r));
+    }
+    recent(project, limit = 10) {
+        return this.db
+            .prepare(`SELECT * FROM observations o WHERE ${VISIBLE} ORDER BY updated_at DESC, id DESC LIMIT ?`)
+            .all(project, Math.min(Math.max(limit, 1), 50)).map(hit);
+    }
+    pinned(project, limit = 10) {
+        return this.db
+            .prepare(`SELECT * FROM observations o WHERE ${VISIBLE} AND pinned=1 ORDER BY updated_at DESC LIMIT ?`)
+            .all(project, Math.min(Math.max(limit, 1), 50)).map(hit);
+    }
+    get(id, project) {
+        const r = this.db
+            .prepare(`SELECT * FROM observations o WHERE id=? AND ${VISIBLE}`)
+            .get(id, project);
+        if (!r)
+            return undefined;
+        const now = this.now();
+        this.db
+            .prepare("UPDATE observations SET access_count=access_count+1, last_accessed_at=? WHERE id=?")
+            .run(now, id);
+        return {
+            id: r.id,
+            project: r.project,
+            scope: r.scope,
+            type: r.type,
+            title: r.title,
+            content: r.content,
+            ...(r.topic_key ? { topicKey: r.topic_key } : {}),
+            ...(r.session_id ? { session: r.session_id } : {}),
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+            revisionCount: r.revision_count,
+            duplicateCount: r.duplicate_count,
+            accessCount: r.access_count + 1,
+            pinned: !!r.pinned,
+        };
+    }
+    timeline(id, project, before = 3, after = 3) {
+        const anchor = this.db
+            .prepare(`SELECT * FROM observations o WHERE id=? AND ${VISIBLE}`)
+            .get(id, project);
+        if (!anchor)
+            return [];
+        const b = Math.min(Math.max(before, 0), 10), a = Math.min(Math.max(after, 0), 10);
+        const scope = anchor.session_id ? "o.session_id=?" : "o.project=?";
+        const key = anchor.session_id ?? anchor.project;
+        const older = this.db
+            .prepare(`SELECT * FROM observations o WHERE ${VISIBLE} AND ${scope} AND (o.created_at<? OR (o.created_at=? AND o.id<?))
+         ORDER BY o.created_at DESC, o.id DESC LIMIT ?`)
+            .all(project, key, anchor.created_at, anchor.created_at, id, b);
+        const newer = this.db
+            .prepare(`SELECT * FROM observations o WHERE ${VISIBLE} AND ${scope} AND (o.created_at>? OR (o.created_at=? AND o.id>?))
+         ORDER BY o.created_at, o.id LIMIT ?`)
+            .all(project, key, anchor.created_at, anchor.created_at, id, a);
+        return [...older.reverse(), anchor, ...newer].map(hit);
+    }
+    pin(id, project, pinned) {
+        return (this.db
+            .prepare(`UPDATE observations SET pinned=? WHERE id IN (SELECT id FROM observations o WHERE id=? AND ${VISIBLE})`)
+            .run(pinned ? 1 : 0, id, project).changes > 0);
+    }
+    forget(id, project, hard = false) {
+        const visible = `id IN (SELECT id FROM observations o WHERE id=? AND ${VISIBLE})`;
+        return hard
+            ? this.db.prepare(`DELETE FROM observations WHERE ${visible}`).run(id, project).changes > 0
+            : this.db
+                .prepare(`UPDATE observations SET deleted_at=? WHERE ${visible}`)
+                .run(this.now(), id, project).changes > 0;
+    }
+    count(project) {
+        const row = this.db
+            .prepare(`SELECT SUM(scope='project' AND project=?) AS p, SUM(scope='personal') AS s FROM observations
+         WHERE deleted_at IS NULL`)
+            .get(project);
+        return { project: row.p ?? 0, personal: row.s ?? 0 };
+    }
+    recordPrompt(project, session, content) {
+        const text = cap(redactPrivate(content).trim(), 2_000);
+        if (!text)
+            return;
+        const now = this.now();
+        this.db
+            .prepare("INSERT INTO memory_sessions(id,project,started_at) VALUES(?,?,?) ON CONFLICT(id) DO NOTHING")
+            .run(session, project, now);
+        this.db
+            .prepare("INSERT INTO user_prompts(session_id,content,project,created_at) VALUES(?,?,?,?)")
+            .run(session, text, project, now);
+    }
+    recentPrompts(project, limit = 5) {
+        return this.db
+            .prepare("SELECT session_id, content, created_at FROM user_prompts WHERE project=? ORDER BY created_at DESC, id DESC LIMIT ?")
+            .all(project, Math.min(Math.max(limit, 1), 50)).map((r) => ({ session: r.session_id, content: r.content, createdAt: r.created_at }));
+    }
+    saveSummary(project, session, content) {
+        const now = this.now();
+        const stored = cap(redactPrivate(content).trim(), MAX_OBSERVATION_LENGTH);
+        this.db
+            .prepare(`INSERT INTO memory_sessions(id,project,started_at,ended_at,summary) VALUES(?,?,?,?,?)
+         ON CONFLICT(id) DO UPDATE SET summary=excluded.summary, ended_at=excluded.ended_at`)
+            .run(session, project, now, now, stored);
+        return stored;
+    }
+    lastSummary(project) {
+        const row = this.db
+            .prepare("SELECT id, project, summary, ended_at FROM memory_sessions WHERE project=? AND summary IS NOT NULL ORDER BY ended_at DESC LIMIT 1")
+            .get(project);
+        return row
+            ? { project: row.project, session: row.id, content: row.summary, createdAt: row.ended_at }
+            : undefined;
+    }
+    /** Session summary of one session, used to confirm an archive write. */
+    summaryOf(session) {
+        const row = this.db.prepare("SELECT summary FROM memory_sessions WHERE id=?").get(session);
+        return row?.summary ?? undefined;
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,16 @@
+import { type ToolDefinition } from "@alisio/sdk";
+import { type MemoryScope, type MemoryStore } from "./types.ts";
+export interface MemoryToolDeps {
+    store: MemoryStore;
+    project: string;
+    defaultScope: MemoryScope;
+    budgetTokens: number;
+    /** Called after a successful write so the plugin can refresh its status. */
+    onWrite?: (action: string) => void;
+}
+export declare function memoryContextText(deps: MemoryToolDeps, session?: string): string | undefined;
+/**
+ * Memory tools use the `internal` effect: they write only to Alisio's memory store, so they
+ * remain available under --read-only. Results follow progressive disclosure.
+ */
+export declare function memoryTools(deps: MemoryToolDeps): ToolDefinition[];

package/dist/tools.js

@@ -0,0 +1,165 @@
+import { textResult } from "@alisio/sdk";
+import { formatObservation, renderMemoryContext, suggestTopicKey } from "./format.js";
+import { MEMORY_TYPES } from "./types.js";
+const schema = (properties, required = []) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const str = (maxLength) => ({ type: "string", minLength: 1, maxLength });
+const id = { type: "integer", minimum: 1 };
+const json = (value) => textResult(JSON.stringify(value));
+export function memoryContextText(deps, session) {
+    const { store, project } = deps;
+    const summary = store.lastSummary(project);
+    const pinned = store.pinned(project, 10);
+    const recent = store.recent(project, 20);
+    const prompts = store.recentPrompts(project, 5).map((p) => p.content);
+    if (!summary && !pinned.length && !recent.length && !prompts.length)
+        return undefined;
+    return renderMemoryContext({
+        project,
+        ...(session ? { session } : {}),
+        ...(summary ? { summary: summary.content } : {}),
+        prompts,
+        pinned,
+        recent,
+    }, deps.budgetTokens);
+}
+/**
+ * Memory tools use the `internal` effect: they write only to Alisio's memory store, so they
+ * remain available under --read-only. Results follow progressive disclosure.
+ */
+export function memoryTools(deps) {
+    const { store, project } = deps;
+    return [
+        {
+            name: "memory_save",
+            effect: "internal",
+            description: "Save a durable observation (decision, bugfix, discovery, pattern, architecture, config, preference, learning). Reuse topic_key (family/description) to update instead of duplicating.",
+            inputSchema: schema({
+                title: str(200),
+                type: { type: "string", enum: [...MEMORY_TYPES] },
+                what: str(20_000),
+                why: { type: "string", maxLength: 10_000 },
+                where: { type: "string", maxLength: 5_000 },
+                learned: { type: "string", maxLength: 10_000 },
+                topic_key: { type: "string", maxLength: 120 },
+                scope: { type: "string", enum: ["project", "personal"] },
+            }, ["title", "type", "what"]),
+            async execute(input, context) {
+                const type = input.type;
+                const result = store.save({
+                    project,
+                    scope: input.scope ?? deps.defaultScope,
+                    type,
+                    title: String(input.title),
+                    content: formatObservation({
+                        title: String(input.title),
+                        type,
+                        what: String(input.what),
+                        ...(typeof input.why === "string" ? { why: input.why } : {}),
+                        ...(typeof input.where === "string" ? { where: input.where } : {}),
+                        ...(typeof input.learned === "string" ? { learned: input.learned } : {}),
+                    }),
+                    ...(typeof input.topic_key === "string" && input.topic_key.trim()
+                        ? { topicKey: input.topic_key }
+                        : {}),
+                    ...(context.session ? { session: context.session } : {}),
+                    source: "memory_save",
+                });
+                deps.onWrite?.(result.action);
+                return json(input.topic_key
+                    ? result
+                    : { ...result, suggested_topic_key: suggestTopicKey(type, String(input.title)) });
+            },
+        },
+        {
+            name: "memory_search",
+            effect: "internal",
+            description: "Search memories (this project plus personal ones). Returns compact rows; use memory_get for full content. Use 1-2 keywords of 3+ characters.",
+            inputSchema: schema({
+                query: str(500),
+                type: { type: "string", enum: [...MEMORY_TYPES] },
+                scope: { type: "string", enum: ["project", "personal"] },
+                limit: { type: "integer", minimum: 1, maximum: 20 },
+                match: { type: "string", enum: ["all", "any"] },
+                all_projects: { type: "boolean" },
+            }, ["query"]),
+            async execute(input) {
+                const options = {
+                    ...(input.type ? { type: input.type } : {}),
+                    ...(input.scope ? { scope: input.scope } : {}),
+                    limit: Number(input.limit ?? 8),
+                    allProjects: input.all_projects === true,
+                };
+                let mode = input.match ?? "all";
+                let results = store.search(project, String(input.query), { ...options, mode });
+                if (!results.length && !input.match) {
+                    mode = "any";
+                    results = store.search(project, String(input.query), { ...options, mode });
+                }
+                return json({ mode, results });
+            },
+        },
+        {
+            name: "memory_get",
+            effect: "internal",
+            description: "Get the full content of one memory by id.",
+            inputSchema: schema({ id }, ["id"]),
+            async execute(input) {
+                const record = store.get(Number(input.id), project);
+                return record ? json(record) : textResult(`Memory ${String(input.id)} not found`, true);
+            },
+        },
+        {
+            name: "memory_context",
+            effect: "internal",
+            description: "Recent memories, pinned memories, recent prompts and the last session summary for this project (budgeted).",
+            inputSchema: schema({}),
+            async execute(_input, context) {
+                return json({ context: memoryContextText(deps, context.session) ?? "No memories yet." });
+            },
+        },
+        {
+            name: "memory_timeline",
+            effect: "internal",
+            description: "Chronological neighbours of a memory within the same session.",
+            inputSchema: schema({
+                id,
+                before: { type: "integer", minimum: 0, maximum: 10 },
+                after: { type: "integer", minimum: 0, maximum: 10 },
+            }, ["id"]),
+            async execute(input) {
+                return json({
+                    timeline: store.timeline(Number(input.id), project, Number(input.before ?? 3), Number(input.after ?? 3)),
+                });
+            },
+        },
+        {
+            name: "memory_pin",
+            effect: "internal",
+            description: "Pin (or unpin) a memory so it is always included in memory context.",
+            inputSchema: schema({ id, pinned: { type: "boolean" } }, ["id"]),
+            async execute(input) {
+                const ok = store.pin(Number(input.id), project, input.pinned !== false);
+                if (ok)
+                    deps.onWrite?.("pinned");
+                return json({ pinned: ok && input.pinned !== false, found: ok });
+            },
+        },
+        {
+            name: "memory_forget",
+            effect: "internal",
+            description: "Forget a memory (soft delete; hard=true removes it permanently).",
+            inputSchema: schema({ id, hard: { type: "boolean" } }, ["id"]),
+            async execute(input) {
+                const forgotten = store.forget(Number(input.id), project, input.hard === true);
+                if (forgotten)
+                    deps.onWrite?.("forgotten");
+                return json({ forgotten });
+            },
+        },
+    ];
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/** Memory plugin contract. Core never imports this module. */
+export declare const MEMORY_TYPES: readonly ["decision", "bugfix", "discovery", "pattern", "architecture", "config", "preference", "learning"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/** `project` memories belong to one project id; `personal` ones are visible from every project. */
+export type MemoryScope = "project" | "personal";
+export interface MemoryInput {
+    project: string;
+    scope: MemoryScope;
+    type: MemoryType;
+    title: string;
+    /** Body, conventionally **What** / **Why** / **Where** / **Learned**. */
+    content: string;
+    topicKey?: string;
+    session?: string;
+    /** Producer, e.g. memory_save or compaction (Engram's tool_name). */
+    source?: string;
+}
+export interface MemoryRecord extends Omit<MemoryInput, "source"> {
+    id: number;
+    createdAt: number;
+    updatedAt: number;
+    revisionCount: number;
+    duplicateCount: number;
+    accessCount: number;
+    pinned: boolean;
+}
+/** Compact row: progressive disclosure keeps full bodies behind get(id). */
+export interface MemoryHit {
+    id: number;
+    type: MemoryType;
+    title: string;
+    snippet: string;
+    scope: MemoryScope;
+    topicKey?: string;
+    updatedAt: number;
+    pinned?: boolean;
+}
+export interface SessionSummary {
+    project: string;
+    session: string;
+    content: string;
+    createdAt: number;
+}
+export interface SearchOptions {
+    limit?: number;
+    type?: MemoryType;
+    scope?: MemoryScope;
+    /** `all` (default) requires every term; `any` matches any term. */
+    mode?: "all" | "any";
+    /** Search every project instead of this project plus personal memories. */
+    allProjects?: boolean;
+}
+export type SaveAction = "created" | "updated" | "duplicate";
+/** Engram-style local store: no network, no embeddings; soft-deleted rows are always hidden. */
+export interface MemoryStore {
+    save(input: MemoryInput): {
+        id: number;
+        action: SaveAction;
+    };
+    search(project: string, query: string, options?: SearchOptions): MemoryHit[];
+    recent(project: string, limit?: number): MemoryHit[];
+    pinned(project: string, limit?: number): MemoryHit[];
+    get(id: number, project: string): MemoryRecord | undefined;
+    timeline(id: number, project: string, before?: number, after?: number): MemoryHit[];
+    pin(id: number, project: string, pinned: boolean): boolean;
+    forget(id: number, project: string, hard?: boolean): boolean;
+    count(project: string): {
+        project: number;
+        personal: number;
+    };
+    recordPrompt(project: string, session: string, content: string): void;
+    recentPrompts(project: string, limit?: number): {
+        session: string;
+        content: string;
+        createdAt: number;
+    }[];
+    /** Stores (redacted, capped) and returns the persisted text. */
+    saveSummary(project: string, session: string, content: string): string;
+    /** Summary of one session, used to confirm an archive write. */
+    summaryOf(session: string): string | undefined;
+    lastSummary(project: string): SessionSummary | undefined;
+    close(): void;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/** Memory plugin contract. Core never imports this module. */
+export const MEMORY_TYPES = [
+    "decision",
+    "bugfix",
+    "discovery",
+    "pattern",
+    "architecture",
+    "config",
+    "preference",
+    "learning",
+];

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@alisio/plugin-memory",
+  "version": "0.1.0-alpha.3",
+  "description": "Engram-style persistent memory for Alisio: SQLite FTS5 observations with topic-key upserts, memory-aware compaction, session summaries and recall tools. Built-in, disableable plugin.",
+  "author": "Gustavo Gutiérrez",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GustavoGutierrez/alisio.git",
+    "directory": "packages/plugin-memory"
+  },
+  "homepage": "https://gustavogutierrez.github.io/alisio/",
+  "bugs": {
+    "url": "https://github.com/GustavoGutierrez/alisio/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "llm",
+    "agent-harness",
+    "openai-compatible",
+    "alisio-plugin",
+    "plugins",
+    "memory",
+    "fts5",
+    "sqlite"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.16"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "@alisio/sdk": "^0.1.0-alpha.2"
+  },
+  "devDependencies": {
+    "@alisio/sdk": "0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}