@ai-ecoverse/slicc-agent 3.13.1 → 3.15.0

package/dist/types/memory/context.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from '@earendil-works/chord';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+export declare const CANDIDATES: string[];
+export declare const TRUSTED_ROOTS: string[];
+export declare const UNTRUSTED = "outside /home: mounted folders and other roots load once SLICC can trust a folder";
+export type ContextFile = {
+    path: string;
+    content: string;
+};
+export type Skipped = {
+    path: string;
+    reason: string;
+};
+export type ContextFiles = {
+    files: ContextFile[];
+    skipped: Skipped[];
+};
+type Files = Pick<ExecutionEnv, 'readTextFile' | 'canonicalPath'>;
+export declare function trusted(path: string): boolean;
+export declare function loadContextFiles(env: Files, options: {
+    cwd: string;
+    agentDir: string;
+    global?: boolean;
+    project?: boolean;
+}, context: Context): Promise<ContextFiles>;
+export declare function renderContextFiles({ files, skipped }: ContextFiles): string | undefined;
+export {};

package/dist/types/memory/format.d.ts

@@ -0,0 +1,67 @@
+export type MemoryTag = 'user' | 'feedback' | 'project';
+export interface MemoryEntry {
+    id: string;
+    scope: string;
+    section: string;
+    title: string;
+    body: string;
+    tag: MemoryTag | null;
+    updatedAt: number;
+    source: 'entry' | 'notes';
+}
+export interface MemoryScope {
+    id: string;
+    label: string;
+    group?: 'cones' | 'roles';
+}
+export type Entry = {
+    title: string;
+    tag: MemoryTag | null;
+    body: string;
+};
+export type Section = {
+    name: string;
+    intro: string;
+    entries: Entry[];
+};
+export type MemoryDoc = {
+    head: string;
+    sections: Section[];
+};
+export declare const MEMORY_FILE = "MEMORY.md";
+export declare const NOTES = "Notes";
+export declare const MAX_LINES = 200;
+export declare const MAX_BYTES: number;
+export declare function slugOf(text: string): string;
+export declare function parseMemory(text: string): MemoryDoc;
+export declare function serializeMemory(doc: MemoryDoc): string;
+export declare function memoryEntries(doc: MemoryDoc, scope: string, updatedAt: number): MemoryEntry[];
+export type Change = {
+    kind: 'save';
+    id?: string;
+    section: string;
+    title: string;
+    body: string;
+    tag: MemoryTag | null;
+} | {
+    kind: 'remove';
+    id?: string;
+    section?: string;
+    title?: string;
+};
+export declare function oneLine(text: string): string;
+export declare function demote(body: string): string;
+export declare function applyChange(doc: MemoryDoc, scope: string, change: Change): {
+    doc: MemoryDoc;
+    found: boolean;
+};
+export declare function excerpt(text: string): {
+    text: string;
+    capped: boolean;
+};
+export declare function byteLength(text: string): number;
+export declare const REDACTED = "[redacted]";
+export declare function redactSecrets(text: string): {
+    text: string;
+    count: number;
+};

package/dist/types/memory/index.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@earendil-works/chord';
+import { type Extension, type Registry, type ToolRegistration } from '@earendil-works/pi-durable';
+import { type MemoryAttach, type MemoryRuntime } from './runtime.ts';
+export { MEMORY_WRITE, whoIs } from './prompt.ts';
+export type { MemoryAttach, MemoryDraft, MemoryRuntime } from './runtime.ts';
+export { USAGE } from './runtime.ts';
+export interface MemorySetup {
+    extension: Extension;
+    tools: readonly ToolRegistration[];
+    attach(options: MemoryAttach, context: Context): Promise<MemoryRuntime>;
+}
+export declare function setupMemory(registry: Registry): MemorySetup;

package/dist/types/memory/prompt.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from '@earendil-works/chord';
+import { Type } from '@earendil-works/pi-ai';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Agents, AgentsState, ScoopRecord } from '../agents.ts';
+import { type MemoryFiles, type Place, type Written } from './store.ts';
+export declare const MEMORY_WRITE = "memory_write";
+export type Host = {
+    agents: Agents;
+    env: ExecutionEnv;
+    home: string;
+    files: MemoryFiles;
+    changed: (context: Context) => Promise<void>;
+};
+export type Who = {
+    kind: 'cone';
+    id: string;
+} | {
+    kind: 'scoop';
+    id: string;
+    record: ScoopRecord;
+} | {
+    kind: 'other';
+};
+type Problem = {
+    problem: string;
+};
+export declare function whoIs(state: Readonly<AgentsState>, conversation: number): Who;
+export declare function ownPlace(host: Host, who: Who, cwd: string, context: Context): Promise<Place | Problem>;
+export declare function contextSection(ready: Promise<Host>): import("@earendil-works/pi-durable").PromptSection<import("@earendil-works/pi-durable").ToolRegistration>;
+export declare function memorySection(ready: Promise<Host>): import("@earendil-works/pi-durable").PromptSection<import("@earendil-works/pi-durable").ToolRegistration>;
+type Args = {
+    section: string;
+    title: string;
+    body?: string;
+    tag?: 'user' | 'feedback' | 'project';
+    remove?: boolean;
+    scope?: 'own' | 'global';
+};
+export declare function writeAnswer(args: Args, place: Place, written: Written): string;
+export declare function memoryWriteTool(ready: Promise<Host>): import("@earendil-works/pi-durable").ToolRegistration<Type.TObject<{
+    section: Type.TString;
+    title: Type.TString;
+    body: Type.TOptional<Type.TString>;
+    tag: Type.TOptional<Type.TUnion<[Type.TLiteral<"user">, Type.TLiteral<"feedback">, Type.TLiteral<"project">]>>;
+    remove: Type.TOptional<Type.TBoolean>;
+    scope: Type.TOptional<Type.TUnion<[Type.TLiteral<"own">, Type.TLiteral<"global">]>>;
+}>, import("@earendil-works/chord").JsonValue>;
+export {};

package/dist/types/memory/runtime.d.ts

@@ -0,0 +1,45 @@
+import { type Context, type ReplicatedState } from '@earendil-works/chord';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Agents } from '../agents.ts';
+import type { Role } from '../roles/roles.ts';
+import { type MemoryEntry, type MemoryScope, type MemoryTag } from './format.ts';
+import type { Host } from './prompt.ts';
+import { type Place } from './store.ts';
+export type Answer = {
+    code: number;
+    out: string;
+};
+export interface MemoryDraft {
+    id?: string;
+    scope: string;
+    section: string;
+    title: string;
+    body: string;
+    tag: MemoryTag | null;
+}
+export interface MemoryRuntime {
+    readonly memories: ReplicatedState<MemoryEntry[]>;
+    readonly scopes: ReplicatedState<MemoryScope[]>;
+    save(draft: MemoryDraft, context: Context): Promise<MemoryEntry>;
+    remove(id: string, context: Context): Promise<boolean>;
+    command(argv: readonly string[], caller: string | null, context: Context): Promise<Answer>;
+    reload(context: Context): Promise<void>;
+    close(context: Context): Promise<void>;
+}
+export interface MemoryAttach {
+    agents: Agents;
+    env: ExecutionEnv;
+    home: string;
+    reloadMs: number;
+    roles?: (context: Context) => Promise<{
+        roles: readonly Role[];
+    } | undefined>;
+}
+export declare const USAGE = "usage:\n  memory show [<scope>]   print a memory file (yours by default)\n  memory scopes           every memory scope, its entries and its file\n\nScopes: global (everyone), a cone's id, or role:<path> for a role's memory.\nAgents write memory with the memory_write tool; the files are plain markdown you can edit.\n";
+type Listed = Place & {
+    group?: 'cones' | 'roles';
+    name: string;
+};
+export declare function listPlaces(options: MemoryAttach, context: Context): Promise<Listed[]>;
+export declare function attachMemory(options: MemoryAttach, connect: (host: Host) => void, context: Context): Promise<MemoryRuntime>;
+export {};

package/dist/types/memory/store.d.ts

@@ -0,0 +1,41 @@
+import type { Context } from '@earendil-works/chord';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import { type Change, type MemoryEntry } from './format.ts';
+export declare const GLOBAL = "global";
+export declare const ROLE_PREFIX = "role:";
+export type RoleMemory = {
+    scope: 'user' | 'project';
+    path: string;
+};
+export type Place = {
+    scope: string;
+    file: string;
+    label: string;
+};
+export type Written = {
+    entry: MemoryEntry | null;
+    found: boolean;
+    bytes: number;
+    redacted: number;
+    file: string;
+};
+export declare function memoryRoot(home: string): string;
+export declare function roleRoot(home: string): string;
+export declare function safePath(path: string): string | null;
+export declare function placeOf(home: string, scope: string): Place | null;
+export declare function projectRoot(env: Pick<ExecutionEnv, 'exists'>, cwd: string, context: Context): Promise<string | null>;
+export declare function rolePlace(env: Pick<ExecutionEnv, 'exists'>, home: string, memory: RoleMemory, cwd: string, context: Context): Promise<Place | {
+    problem: string;
+}>;
+type Files = Pick<ExecutionEnv, 'readTextFile' | 'writeFile' | 'createDir' | 'canonicalPath' | 'fileInfo'>;
+export declare class MemoryFiles {
+    #private;
+    constructor(env: Files);
+    read(file: string, context: Context): Promise<{
+        text: string;
+        updatedAt: number;
+    } | null>;
+    entries(place: Place, context: Context): Promise<MemoryEntry[]>;
+    change(place: Place, change: Change, context: Context): Promise<Written>;
+}
+export {};

package/dist/types/roles/frontmatter.d.ts

@@ -4,4 +4,4 @@ export interface Frontmatter {
     body: string;
     problems: string[];
 }
-export declare function parseFrontmatter(text: string): Frontmatter;
+export declare function parseFrontmatter(text: string, mappings?: readonly string[]): Frontmatter;

package/dist/types/roles/roles.d.ts

@@ -1,5 +1,7 @@
 import type { Context } from '@earendil-works/chord';
 import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { RoleMemory } from '../memory/store.ts';
+import { type FrontmatterValue } from './frontmatter.ts';
 export type RoleSource = 'builtin' | 'package' | 'user' | 'project';
 export type Thinking = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 export interface Role {
@@ -12,6 +14,11 @@ export interface Role {
     thinking?: Thinking;
     aliases: string[];
     output?: string;
+    memory?: RoleMemory;
+    context?: {
+        project: boolean;
+        global: boolean;
+    };
     source: RoleSource;
     path: string;
 }
@@ -32,6 +39,7 @@ export interface RoleSourceDir {
     source: RoleSource;
     dir: string;
 }
+export declare function roleMemory(value: FrontmatterValue): RoleMemory | undefined;
 export declare function parseRole(text: string, source: RoleSource, path: string, warnings: string[]): Role | undefined;
 export interface LoadOptions {
     files: RoleFiles;

package/dist/types/scoops/cli.d.ts

@@ -20,6 +20,7 @@ export interface CliOptions {
     alive?: (pid: number) => Promise<boolean>;
     now?: () => number;
     sprinkle?: (argv: readonly string[], caller: string | null, context: Context) => Promise<Answer>;
+    memory?: (argv: readonly string[], caller: string | null, context: Context) => Promise<Answer>;
 }
 export type Deps = CliOptions & {
     now: () => number;

package/dist/types/scoops/index.d.ts

@@ -25,6 +25,7 @@ export interface AttachOptions {
     alive?: (pid: number) => Promise<boolean>;
     reads: () => readonly string[];
     sprinkle?: CliOptions['sprinkle'];
+    memory?: CliOptions['memory'];
 }
 export interface ScoopsRuntime {
     roles(context: Context): Promise<Roles>;

package/dist/types/scoops/requests.d.ts

@@ -6,7 +6,7 @@ export declare const PROTOCOL = "slicc-agent/1";
 export declare const STALE_MS: number;
 export interface Request {
     id: string;
-    as: 'agent' | 'subagent' | 'sprinkle';
+    as: 'agent' | 'subagent' | 'sprinkle' | 'memory';
     caller: string;
     cwd: string;
     pid: number | null;

package/dist/types/scoops/service.d.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@earendil-works/chord';
 import { type AgentChange, type AnyTask, type Conversation, type Harness, type ToolRegistration } from '@earendil-works/pi-durable';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
 import { type Agents, type AgentsState, type Mark, type ScoopRecord } from '../agents.ts';
 import type { ProcessGroups } from '../kernel/groups.ts';
 import type { Licks } from '../licks/licks.ts';
@@ -47,6 +48,7 @@ export interface ScoopsHost {
     groups?: ProcessGroups;
     tools?: readonly ToolRegistration[];
     reads?: () => readonly string[];
+    files?: Pick<ExecutionEnv, 'remove' | 'createDir'>;
 }
 export interface Rewound {
     stopped: string[];
@@ -73,6 +75,7 @@ export interface SpawnRequest {
         read: string[];
     };
     cwd?: string;
+    origin?: string;
     instructions?: string;
     target?: string | null;
     asker?: string | null;

package/dist/types/services.d.ts

@@ -1,5 +1,6 @@
 import { type Context, type JsonValue, type ReplicatedState } from '@earendil-works/chord';
 import type { ConversationView } from '@earendil-works/pi-durable';
+import type { MemoryEntry, MemoryScope, MemoryTag } from './memory/format.ts';
 import type { Sprinkle } from './sprinkles/kind.ts';
 export type SendMode = 'steer' | 'followUp' | 'reject';
 export interface SendRequest {
@@ -61,6 +62,18 @@ export interface AgentControl {
         delivered: boolean;
     }>;
     sprinkleCall(sprinkleId: string, method: string, args: JsonValue[], context: Context): Promise<JsonValue>;
+    memorySave(draft: MemoryDraft, context: Context): Promise<MemoryEntry>;
+    memoryRemove(id: string, context: Context): Promise<{
+        removed: boolean;
+    }>;
+}
+export interface MemoryDraft {
+    id: string | null;
+    scope: string;
+    section: string;
+    title: string;
+    body: string;
+    tag: MemoryTag | null;
 }
 export type Created = {
     id: string;
@@ -120,6 +133,8 @@ export interface AgentTranscript {
     readonly views: ReplicatedState<Record<string, ConversationView>>;
     readonly commands: ReplicatedState<Command[]>;
     readonly sprinkles: ReplicatedState<Sprinkle[]>;
+    readonly memories: ReplicatedState<MemoryEntry[]>;
+    readonly memoryScopes: ReplicatedState<MemoryScope[]>;
 }
 export interface Command {
     name: string;

package/dist/types/spectrum/index.d.ts

@@ -1,9 +1,11 @@
 import type { AgentConnection } from '../client.ts';
 import { AgentAdapter } from './agent-port.ts';
+import { MemoryAdapter } from './memory-port.ts';
 import { type Login, SettingsAdapter } from './settings-port.ts';
 import { SprinkleAdapter } from './sprinkle-port.ts';
 import { TrayAdapter } from './tray-port.ts';
 export { AgentAdapter, CONE } from './agent-port.ts';
+export { MemoryAdapter } from './memory-port.ts';
 export { assistant, errorAction, errorPart, isBusy, queued, textOf, toMessages, } from './messages.ts';
 export { type Login, SETTINGS_KEY, SettingsAdapter } from './settings-port.ts';
 export { SprinkleAdapter } from './sprinkle-port.ts';
@@ -16,4 +18,5 @@ export declare function createAgentModel(connection: AgentConnection, options?:
     settings: SettingsAdapter;
     tray: TrayAdapter;
     sprinkles: SprinkleAdapter;
+    memory: MemoryAdapter;
 };

package/dist/types/spectrum/memory-port.d.ts

@@ -0,0 +1,12 @@
+import type { Memory, MemoryDraft, MemoryEvents, MemoryPort } from '@ai-ecoverse/slicc-spectrum/ui';
+import type { AgentConnection } from '../client.ts';
+import { type MemoryScope } from '../memory/format.ts';
+import { Emitter } from './emitter.ts';
+export declare class MemoryAdapter extends Emitter<MemoryEvents> implements MemoryPort {
+    #private;
+    constructor(connection: AgentConnection);
+    list(): readonly Memory[];
+    scopes(): readonly MemoryScope[];
+    save(draft: MemoryDraft): Memory;
+    remove(id: string): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-agent",
-  "version": "3.13.1",
+  "version": "3.15.0",
   "description": "SLICC's agent core on pi durable: an agent worker, session storage, remoting and pi extensions",
   "type": "module",
   "license": "Apache-2.0",
@@ -61,8 +61,8 @@
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "1.9.0",
-    "@ai-ecoverse/slicc-spectrum": "1.27.3",
+    "@ai-ecoverse/slicc-shared-web": "1.10.0",
+    "@ai-ecoverse/slicc-spectrum": "1.28.0",
     "@ai-ecoverse/wasm-bash": "5.3.0-8",
     "@ai-ecoverse/wasm-coreutils": "9.7.0-3",
     "@biomejs/biome": "2.5.15",
@@ -87,7 +87,7 @@
     "@sqlite.org/sqlite-wasm": "3.53.4-build2"
   },
   "peerDependencies": {
-    "@ai-ecoverse/slicc-spectrum": "^1.27.2"
+    "@ai-ecoverse/slicc-spectrum": "^1.28.0"
   },
   "peerDependenciesMeta": {
     "@ai-ecoverse/slicc-spectrum": {

package/packages/vfs-root/skills/memory/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: memory
+description: Use this when the user asks what you remember, tells you to remember or forget something, corrects how you work, or when you learn a durable fact worth keeping across conversations. Covers the memory files, the memory_write tool, scopes and the `memory` command.
+---
+
+# Memory
+
+Memory is plain markdown, one `MEMORY.md` per scope, shown to you in the `memory` section of your system prompt (the first 200 lines of each file):
+
+| Scope | File | Who writes it |
+| --- | --- | --- |
+| `global` | `~/.pi/agent/memory/MEMORY.md` | cones, for every agent |
+| a cone (`cone`, `cone-2`, …) | `~/.pi/agent/memory/<cone>/MEMORY.md` | that cone |
+| a role (`role:<path>`) | `~/.pi/agent/agent-memory/<path>/MEMORY.md` | scoops of a role with `memory: { scope: user, path: <path> }` |
+
+A role with `memory: { scope: project, path: <path> }` keeps it in `<project>/.pi/agent-memory/<path>/MEMORY.md`, where the project is the nearest folder above the scoop's working directory with a `.pi` or `.git`, inside /home.
+
+## Writing
+
+Use `memory_write` rather than editing the files:
+
+- `section` and `title` name the entry; saving the same section and title again replaces it.
+- `tag` is `user` (who the user is), `feedback` (how they want you to work) or `project` (facts about their work).
+- `remove: true` forgets an entry. `scope: "global"` writes the shared file (cones only).
+
+Keep entries short and durable: a preference, a correction, a convention, a project fact. Don't save one-off task details, transcripts, or anything secret (keys, tokens, passwords, signed or launch URLs); memory_write redacts what looks like one. Each file holds 16 KB; when it's full, merge or remove entries before adding.
+
+The file format, if you or the user edit it by hand:
+
+```markdown
+## Preferences
+
+### Lead with the result
+tag: feedback
+
+Keep replies short. Lead with the result, then the detail.
+```
+
+## The `memory` command
+
+- `memory scopes` lists every scope with its entry count and file.
+- `memory show [<scope>]` prints a memory file, yours by default.
+
+The user sees and edits the same entries in the Memory panel.
+
+## Instructions are not memory
+
+`AGENTS.md` and `CLAUDE.md` files hold instructions the user wrote: `~/.pi/agent/AGENTS.md` and the ones on your working directory's path inside /home are in the `project_context` section. Files in mounted folders are listed there as not loaded; they load once SLICC can trust a folder.