@alisio/plugin-memory 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -1,14 +1,74 @@
 # @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).
+**Engram-style persistent memory for [Alisio](https://github.com/GustavoGutierrez/alisio).** The
+model saves decisions, bug fixes and discoveries across sessions, and recalls them with context;
+compaction and session end turn meetings into structured, searchable memory.
 
-- 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.
+## What it is
 
-Configuration lives under `builtinPlugins.memory`. Docs: [Memory plugin](https://gustavogutierrez.github.io/alisio/memory).
+Shipped as a built-in plugin of the `alisio` CLI (disable with `--disable-plugin memory` or
+`builtinPlugins.memory.enabled: false`). It depends only on `@alisio/sdk` and stores data through
+the SDK storage port — a local SQLite database with FTS5 trigram indexing, BM25 ranking combined
+with recency; no embeddings and no network. The file lives at `<state home>/memory.sqlite` with
+0600 permissions.
 
-Maintainer: Gustavo Gutiérrez · License: MIT
+## Installation
+
+Preinstalled in the `alisio` CLI. For an embedded host, register it through `createApplication`'s
+`builtins` list (the CLI wires it for you).
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `memory_save` | Save or upsert an observation |
+| `memory_search` | Full-text search; AND by default, `match: "any"` and `all_projects` available |
+| `memory_get` | Full observation by ID |
+| `memory_context` | Recent memory context (summaries, prompts, pinned, recent) |
+| `memory_timeline` | Chronological neighbours of a memory within a session |
+| `memory_pin` | Pin (or unpin) a memory so it always appears in memory context |
+| `memory_forget` | Soft delete; `hard: true` removes it permanently |
+
+An observation has a title, a type (`decision`, `bugfix`, `discovery`, `pattern`, `architecture`,
+`config`, `preference`, `learning`), a **What / Why / Where / Learned** body, a `project` or
+`personal` scope and an optional `topic_key` for upserts. All memory tools use the `internal`
+effect: they only touch the memory database, never the workspace, so they stay available under
+`--read-only`.
+
+## Behaviour
+
+- **Memory-aware compaction** — in the same summarizer call, observations are extracted from the
+  discarded span (with upsert/dedup), the checkpoint is archived as the session summary, and
+  relevant memories are injected within a token budget.
+- **Session summaries** — on `/clear`, `/exit` or quitting the TUI, writes a structured
+  Goal/Instructions/Discoveries/Accomplished/Next Steps/Relevant Files summary (option
+  `autoSummary`, on by default).
+- **`/memory` command** — `/memory` (recent), `/memory <query>`, and
+  `/memory show|forget|pin|unpin <id>`; a `mem N` counter in the TUI status bar.
+
+## Configuration
+
+Under `builtinPlugins.memory`:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Enable the plugin |
+| `dbPath` | `<state home>/memory.sqlite` | Database path; relative paths resolve from the config file |
+| `injectBudgetTokens` | `1500` | Token budget (100–20000) for injected memory context |
+| `recallLimit` | `8` | Memories recalled after compaction (0–20) |
+| `autoSummary` | `true` | Write a session summary on session end |
+| `defaultScope` | `project` | `project` or `personal` |
+
+## Docs
+
+[Memory plugin](https://gustavogutierrez.github.io/alisio/memory) ·
+[Configuration](https://gustavogutierrez.github.io/alisio/configuration).
+
+## Requirements
+
+Node.js **>= 22.16** or Bun **>= 1.4.2**.
+
+## License
+
+MIT. Maintained by Gustavo Gutiérrez Mercado. Source: <https://github.com/GustavoGutierrez/alisio> ·
+npm: <https://www.npmjs.com/settings/alisio/packages>.

package/dist/index.js

@@ -8,6 +8,7 @@ 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";
+import { loadVersion } from "./version.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"
@@ -43,7 +44,7 @@ export function createMemoryPlugin(rawOptions, context) {
         id: "memory",
         name: "Memory",
         description: "Persistent memory and memory-aware context compaction",
-        version: "0.1.0",
+        version: loadVersion(import.meta.url),
         apiVersion: 1,
         async setup(api) {
             const project = await projectId(context.workspace);

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads this plugin package's version at runtime so plugin metadata, user-agent defaults and CLI
+ * reports stay in sync with the published package without a build-time constant to update.
+ * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
+ * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
+ * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ */
+export declare function loadVersion(fromHere: string): string;

package/dist/version.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Fallback used when neither the build-time injection nor the package manifest is readable
+ * (e.g. an unpackaged embed). Keep it a development marker, never a publish literal, so it
+ * cannot silently desync from the published package.
+ */
+const FALLBACK = "dev";
+/**
+ * Reads this plugin package's version at runtime so plugin metadata, user-agent defaults and CLI
+ * reports stay in sync with the published package without a build-time constant to update.
+ * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
+ * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
+ * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ */
+export function loadVersion(fromHere) {
+    if (process.env.ALISIO_PACKAGE_VERSION)
+        return process.env.ALISIO_PACKAGE_VERSION;
+    try {
+        const manifest = join(dirname(fileURLToPath(fromHere)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        return typeof parsed.version === "string" && parsed.version ? parsed.version : FALLBACK;
+    }
+    catch {
+        return FALLBACK;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/plugin-memory",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "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",
@@ -46,10 +46,10 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@alisio/sdk": "^0.1.0-alpha.5"
+    "@alisio/sdk": "^0.1.0-alpha.7"
   },
   "devDependencies": {
-    "@alisio/sdk": "0.1.0-alpha.5"
+    "@alisio/sdk": "0.1.0-alpha.7"
   },
   "publishConfig": {
     "access": "public",