@ai-ecoverse/slicc-agent 3.13.1 → 3.14.0

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

@@ -73,6 +73,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.14.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,7 +61,7 @@
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "1.9.0",
+    "@ai-ecoverse/slicc-shared-web": "1.10.0",
     "@ai-ecoverse/slicc-spectrum": "1.27.3",
     "@ai-ecoverse/wasm-bash": "5.3.0-8",
     "@ai-ecoverse/wasm-coreutils": "9.7.0-3",

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.