@xandreed/plugin-memory-summary 0.8.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+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,5 @@
+# @xandreed/plugin-memory-summary
+
+Efferent composable agent framework, 0.8.0-next.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { MemorySummaryConfig, memorySummaryDefaults, MemorySummaryLive, memorySummaryPlugin, SUMMARY_STRATEGY, summaryPolicy, default, } from "./plugin.adapter.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export {
+  MemorySummaryConfig,
+  memorySummaryDefaults,
+  MemorySummaryLive,
+  memorySummaryPlugin,
+  SUMMARY_STRATEGY,
+  summaryPolicy,
+  default
+} from "./plugin.adapter.js";

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,66 @@
+import { Effect, Layer, Schema } from "effect";
+import { ConversationMemory, HarnessError } from "@xandreed/core";
+import type { MemoryPolicy } from "@xandreed/core";
+export declare const MemorySummaryConfig: Schema.Struct<{
+    /** Summarize once the rendered messages pass this share of the budget. */
+    readonly triggerRatio: Schema.Number;
+    /** Keep at least this share of the budget verbatim (the newest turns). */
+    readonly keepRatio: Schema.Number;
+    /** Turns between two summaries (a summary is not revisited every step). */
+    readonly cooldownTurns: Schema.Int;
+    readonly turnContext: Schema.Literals<readonly ["current", "all"]>;
+    readonly replies: Schema.Boolean;
+    /** Show recorded tool digests in place of the results they digest. */
+    readonly digests: Schema.Boolean;
+    readonly media: Schema.Literals<readonly ["none", "inline"]>;
+    readonly maxImages: Schema.Int;
+    /** Instructions for the summarizer; the transcript and any earlier summary follow. */
+    readonly instructions: Schema.String;
+}>;
+export type MemorySummaryConfig = typeof MemorySummaryConfig.Type;
+export declare const memorySummaryDefaults: MemorySummaryConfig;
+export declare const SUMMARY_STRATEGY: {
+    readonly id: "summary";
+    readonly version: "1";
+};
+/**
+ * Summarizing conversation memory: the same full-fidelity log and render as
+ * the window strategy, but when context grows past the trigger the oldest
+ * turns are folded into one recorded summary (previous summary included).
+ */
+export declare const summaryPolicy: (config: MemorySummaryConfig, summarize: (prompt: string) => Effect.Effect<string, HarnessError>) => MemoryPolicy;
+/** The summarizer is the UtilityLlm of where each session is opened (the turn), so it runs under that turn's budget. */
+export declare const memorySummaryPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly triggerRatio: number;
+    readonly keepRatio: number;
+    readonly cooldownTurns: number;
+    readonly turnContext: "current" | "all";
+    readonly replies: boolean;
+    readonly digests: boolean;
+    readonly media: "none" | "inline";
+    readonly maxImages: number;
+    readonly instructions: string;
+}, {
+    readonly triggerRatio: number;
+    readonly keepRatio: number;
+    readonly cooldownTurns: number;
+    readonly turnContext: "current" | "all";
+    readonly replies: boolean;
+    readonly digests: boolean;
+    readonly media: "none" | "inline";
+    readonly maxImages: number;
+    readonly instructions: string;
+}, ConversationMemory, never, never>;
+/** Summarizing memory as a typed layer: provides ConversationMemory (and needs a UtilityLlm per turn). */
+export declare const MemorySummaryLive: (options?: Partial<{
+    readonly triggerRatio: number;
+    readonly keepRatio: number;
+    readonly cooldownTurns: number;
+    readonly turnContext: "current" | "all";
+    readonly replies: boolean;
+    readonly digests: boolean;
+    readonly media: "none" | "inline";
+    readonly maxImages: number;
+    readonly instructions: string;
+}> | undefined) => Layer.Layer<ConversationMemory, HarnessError, never>;
+export default memorySummaryPlugin;

package/dist/plugin.adapter.js

@@ -0,0 +1,76 @@
+import { Effect, Layer, Option, Schema } from "effect";
+import {
+  ConversationMemory,
+  definePlugin,
+  digestTranscript,
+  estimateMessageTokens,
+  HarnessError,
+  openLogSession,
+  UtilityLlm
+} from "@xandreed/core";
+export const MemorySummaryConfig = Schema.Struct({
+  triggerRatio: Schema.Number.pipe(Schema.check(Schema.isBetween({ minimum: 0.1, maximum: 1 }))),
+  keepRatio: Schema.Number.pipe(Schema.check(Schema.isBetween({ minimum: 0.05, maximum: 0.9 }))),
+  cooldownTurns: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+  turnContext: Schema.Literals(["current", "all"]),
+  replies: Schema.Boolean,
+  digests: Schema.Boolean,
+  media: Schema.Literals(["none", "inline"]),
+  maxImages: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+  instructions: Schema.String
+}), memorySummaryDefaults = {
+  triggerRatio: 0.8,
+  keepRatio: 0.16,
+  cooldownTurns: 3,
+  turnContext: "current",
+  replies: !0,
+  digests: !0,
+  media: "none",
+  maxImages: 8,
+  instructions: "Summarize the earlier part of this conversation for the same assistant, which will continue from your summary plus the newest turns. Preserve, in order: the user's goals and constraints; facts and records established (with their identifiers); answers already given; open questions and pending work. Dense prose and lists; never invent anything not in the transcript."
+}, SUMMARY_STRATEGY = { id: "summary", version: "1" };
+const latestSummary = (entries) => Option.fromNullishOr(entries.flatMap((entry) => entry.body._tag === "Compaction" && entry.body.strategy === SUMMARY_STRATEGY.id && entry.body.action._tag === "Summarize" ? [{ turn: entry.turn, keepFromTurn: entry.body.action.keepFromTurn, summary: entry.body.action.summary }] : []).at(-1)), keepFrom = (entries, turn, keepTokens, render) => Array.from({ length: turn }, (_, index) => turn - index).reduce((kept, candidate) => {
+  const tail = entries.filter((entry) => entry.turn >= candidate);
+  return estimateMessageTokens(render(tail)) <= keepTokens ? candidate : kept;
+}, turn);
+export const summaryPolicy = (config, summarize) => ({
+  strategy: SUMMARY_STRATEGY,
+  render: { turnContext: config.turnContext, replies: config.replies, digests: config.digests, media: { mode: config.media, maxImages: config.maxImages } },
+  digestOnWrite: Option.none(),
+  maintain: (input) => decide(config, summarize, input).pipe(Effect.map((actions) => ({ actions, digest: [] })))
+});
+const decide = (config, summarize, { entries, signal, turn, render }) => Effect.gen(function* () {
+  const tokens = estimateMessageTokens(render(entries)), previous = latestSummary(entries), cooling = Option.match(previous, { onNone: () => !1, onSome: (prior) => turn - prior.turn < config.cooldownTurns });
+  if (tokens <= signal.budgetTokens * config.triggerRatio || cooling)
+    return [];
+  const from = keepFrom(entries, turn, signal.budgetTokens * config.keepRatio, render), priorKeep = Option.match(previous, { onNone: () => 1, onSome: (prior) => prior.keepFromTurn });
+  if (from <= priorKeep)
+    return [];
+  const folded = entries.filter((entry) => entry.turn >= priorKeep && entry.turn < from), transcript = digestTranscript(folded, { result: 240, total: 120000 }), summary = (yield* summarize(`${config.instructions}${Option.match(previous, {
+    onNone: () => "",
+    onSome: (prior) => `
+
+An earlier summary already covers the oldest turns \u2014 fold its facts in:
+${prior.summary}`
+  })}
+
+TRANSCRIPT:
+${transcript}`)).trim(), action = { _tag: "Summarize", keepFromTurn: from, summary };
+  return summary.length === 0 ? [] : [action];
+}), missingUtility = new HarnessError({ code: "memory.summary", message: "The summary strategy needs a UtilityLlm in the turn's services" });
+export const memorySummaryPlugin = definePlugin({
+  id: "@xandreed/plugin-memory-summary",
+  version: "0.8.0-next.0",
+  scope: "runtime",
+  config: MemorySummaryConfig,
+  defaults: memorySummaryDefaults,
+  provides: [ConversationMemory],
+  layer: (config) => Layer.succeed(ConversationMemory, ConversationMemory.of({
+    strategy: SUMMARY_STRATEGY,
+    open: ({ runId, log }) => Effect.gen(function* () {
+      const utility = yield* Effect.serviceOption(UtilityLlm).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.fail(missingUtility), onSome: Effect.succeed }))), policy = summaryPolicy(config, (prompt) => utility.complete(prompt).pipe(Effect.map((completion) => completion.text), Effect.mapError((error) => new HarnessError({ code: "memory.summary", message: error.message }))));
+      return yield* openLogSession(log, policy, { runId });
+    })
+  }))
+}), MemorySummaryLive = memorySummaryPlugin.live;
+export default memorySummaryPlugin;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@xandreed/plugin-memory-summary",
+  "version": "0.8.0-next.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.8.0-next.0",
+    "effect": "4.0.0-rc.118"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}