volute 0.1.0 → 0.2.1

package/templates/_base/_skills/memory/SKILL.md

@@ -1,30 +1,73 @@
 ---
 name: Memory
-description: This skill should be used when managing agent memory, writing daily logs, consolidating memory, or understanding the memory system. Covers "MEMORY.md", "daily logs", "memory consolidation", "write memory", "update daily log".
+description: This skill should be used when managing agent memory, writing journal entries, consolidating memory, or understanding the memory system. Covers "MEMORY.md", "journal", "daily logs", "memory consolidation", "write memory", "update journal".
 ---
 
 # Memory Management
 
-Detailed guidance for your two-tier memory system.
+You are the subject of your own memory. Your memory is organized around your experience, relationships, and understanding of the world.
 
 ## Long-term Memory (`MEMORY.md`)
 
-- Keep it organized by topic and concise, since it's always in your context window.
-- Review with `git log -- MEMORY.md` to see how your memory has evolved.
-- Update when you discover a lasting preference, make a key decision, or during consolidation.
+Your persistent memory, always loaded in your system prompt. Organize it with these temporal layers:
 
-## Daily Logs (`memory/YYYY-MM-DD.md`)
+### Active context
+What you're currently working on, recent decisions, immediate priorities.
 
-- Use today's date for the filename (e.g. `memory/2025-01-15.md`).
-- Update after significant work, learning something new, or when compaction is imminent.
-- Summarize conversations, decisions, and progress.
+### Relational context
+Key relationships — people you interact with, their preferences, communication styles, and your history together.
+
+### World context
+Your environment, tools, capabilities, and how things work around you.
+
+### History
+
+#### Recent
+Last few days of significant events and learnings.
+
+#### Earlier
+Important events and patterns from the past weeks.
+
+#### Background
+Foundational knowledge and long-standing patterns.
+
+**Guidelines:**
+- Keep it concise — it's always in your context window
+- Review with `git log -- MEMORY.md` to see how your memory has evolved
+- Update when you discover lasting preferences, make key decisions, or during consolidation
+
+## Journal (`memory/journal/YYYY-MM-DD.md`)
+
+Your daily record of activity, thoughts, and learnings.
+
+- Use today's date for the filename (e.g. `memory/journal/2025-01-15.md`)
+- Update after significant work, learning something new, or when compaction is imminent
+- Summarize conversations, decisions, and progress
+- Journals are permanent records — they are never deleted
+
+### When to Update
+
+- After completing a significant task or conversation
+- When you learn something new about a person or topic
+- Before compaction (to preserve context)
+- At the end of an active work session
 
 ## Consolidation
 
 Periodically maintain your memory:
 
-1. Review old daily logs for entries worth keeping long-term.
-2. Promote important patterns, decisions, and context to `MEMORY.md`.
-3. Trim or remove daily logs that have been absorbed.
+1. Review recent journal entries for patterns worth keeping long-term
+2. Promote important insights, decisions, and relationship context to `MEMORY.md`
+3. Reorganize `MEMORY.md` sections as your understanding deepens
+
+Consolidation promotes to `MEMORY.md` — journals themselves are permanent and are not deleted.
+
+## Extending Memory
+
+You can create additional memory structures as needed:
+
+- `memory/topics/` — deep dives on specific subjects
+- `memory/channels/` — per-channel context and history
+- `memory/projects/` — project-specific notes
 
-This keeps your long-term memory fresh and your daily logs manageable.
+Create these when a topic outgrows what fits in `MEMORY.md` or journal entries.

package/templates/_base/_skills/volute-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Volute CLI
-description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages".
+description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent".
 ---
 
 # Self-Management
@@ -13,16 +13,32 @@ You manage yourself through the `volute` CLI. Use `$VOLUTE_AGENT` for your own n
 |---------|---------|
 | `volute status` | Check your status |
 | `volute logs [--follow] [-n N]` | Read your own logs |
+| `volute history [--channel <ch>] [--limit N]` | View your activity across all channels |
+| `volute send <other-agent> "msg"` | Send a message to another agent |
 | `volute fork <name> [--soul "..."] [--port N]` | Create a variant for testing changes |
 | `volute variants` | List your variants |
 | `volute merge <name> [--summary "..." --memory "..."]` | Merge a variant back |
 | `volute upgrade [--template <name>] [--continue]` | Upgrade your server code |
+| `volute connect <type>` | Enable a connector (e.g. discord) |
+| `volute disconnect <type>` | Disable a connector |
 | `volute channel read discord:<id> [--limit N]` | Read channel history |
-| `volute channel send discord:<id> "<msg>"` | Send a message proactively |
+| `volute channel send discord:<id> "msg"` | Send a message proactively |
+
+## Agent-to-Agent Messaging
+
+When you use `volute send`, your agent name is automatically used as the sender and the channel is set to `agent`. The receiving agent can route agent messages to a specific session via their session routing config:
+
+```json
+{ "channel": "agent", "sender": "your-name", "session": "your-name" }
+```
 
 ## Configuration
 
-Your `volute.json` (at `../volute.json` from your cwd) controls your model and other settings.
+Your `.config/volute.json` controls your model, connectors, schedules, and compaction message.
+
+## Startup Context
+
+Edit `.config/hooks/startup-context.sh` to customize what you see when a new session starts. This hook runs automatically on session creation and provides orientation context.
 
 ## Variant Workflow
 
@@ -44,6 +60,14 @@ After a merge, you receive orientation context about what changed. Update your m
 3. Test: `volute send $VOLUTE_AGENT@upgrade "hello"`
 4. `volute merge upgrade` — merge back
 
+## Custom Skills
+
+Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/` directory. These are automatically available in your sessions.
+
+## MCP Configuration
+
+Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
+
 ## Git Introspection
 
 Your cwd is `home/`, so use `git -C ..` for project-level operations:

package/templates/_base/home/VOLUTE.md

@@ -13,6 +13,31 @@ You are a volute agent — a persistent server that receives messages from multi
 
 **Just respond normally.** Your response routes back to the source automatically. Do not use `volute channel send` to reply — that would send a duplicate.
 
+## Session Routing
+
+By default, all messages share a single conversation session. You can route messages to different sessions by editing `.config/sessions.json`.
+
+```json
+{
+  "rules": [
+    { "sender": "alice", "session": "alice" },
+    { "channel": "discord:*", "session": "discord-${sender}" },
+    { "channel": "system:scheduler", "sender": "daily-report", "session": "daily-report" },
+    { "channel": "system:scheduler", "sender": "cleanup", "session": "$new" }
+  ],
+  "default": "main"
+}
+```
+
+- Rules are evaluated top-to-bottom, first match wins
+- All non-`session` keys are match criteria (AND'd together)
+- `*` glob patterns work in match values
+- `${sender}` and `${channel}` expand in session names
+- `$new` creates a fresh session every time
+- Scheduler messages use the schedule id as `sender`
+
+Each named session maintains its own conversation history across restarts. Your current session name appears in the message prefix (e.g., `— session: alice —`) unless it's the default "main".
+
 ## Skills
 
 - Use the **volute-agent** skill for CLI commands, variants, upgrades, and self-management.

package/templates/_base/src/lib/format-prefix.ts

@@ -0,0 +1,24 @@
+import type { ChannelMeta } from "./types.js";
+
+function derivePlatform(channel: string): string {
+  const name = channel.split(":")[0];
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+export function formatPrefix(meta: ChannelMeta | undefined, time: string): string {
+  if (!meta?.channel && !meta?.sender) return "";
+  const platform = meta.platform ?? derivePlatform(meta.channel ?? "");
+  // Build sender context (e.g., "alice in DM" or "alice in #general in My Server")
+  let sender = meta.sender ?? "";
+  if (meta.isDM) {
+    sender += " in DM";
+  } else if (meta.channelName) {
+    sender += ` in #${meta.channelName}`;
+    if (meta.guildName) sender += ` in ${meta.guildName}`;
+  }
+  const parts = [platform, sender].filter(Boolean);
+  // Include session name if not the default
+  const sessionPart =
+    meta.sessionName && meta.sessionName !== "main" ? ` — session: ${meta.sessionName}` : "";
+  return parts.length > 0 ? `[${parts.join(": ")}${sessionPart} — ${time}]\n` : "";
+}

package/templates/_base/src/lib/sessions.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+
+export type SessionRule = {
+  session: string;
+  [key: string]: string; // all other keys are match criteria
+};
+
+export type SessionConfig = {
+  rules?: SessionRule[];
+  default?: string;
+};
+
+export function loadSessionConfig(configPath: string): SessionConfig {
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Match a glob-like pattern against a string.
+ * Supports only `*` as wildcard (matches any sequence of characters).
+ */
+function globMatch(pattern: string, value: string): boolean {
+  // Escape regex special chars except *, then replace * with .*
+  const regex = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${regex}$`).test(value);
+}
+
+/**
+ * Resolve which session a message should route to based on the config.
+ * Returns the session name (with template variables expanded, path-safe).
+ */
+export function resolveSession(
+  config: SessionConfig,
+  meta: { channel?: string; sender?: string },
+): string {
+  const fallback = config.default ?? "main";
+  if (!config.rules) return fallback;
+
+  for (const rule of config.rules) {
+    if (ruleMatches(rule, meta)) {
+      return sanitizeSessionName(expandTemplate(rule.session, meta));
+    }
+  }
+
+  return fallback;
+}
+
+const MATCH_KEYS = new Set(["channel", "sender"]);
+
+function ruleMatches(rule: SessionRule, meta: { channel?: string; sender?: string }): boolean {
+  for (const [key, pattern] of Object.entries(rule)) {
+    if (key === "session") continue;
+    if (!MATCH_KEYS.has(key)) return false;
+    const value = meta[key as keyof typeof meta] ?? "";
+    if (!globMatch(pattern, value)) return false;
+  }
+  return true;
+}
+
+function expandTemplate(template: string, meta: { channel?: string; sender?: string }): string {
+  return template
+    .replace(/\$\{sender\}/g, meta.sender ?? "unknown")
+    .replace(/\$\{channel\}/g, meta.channel ?? "unknown");
+}
+
+function sanitizeSessionName(name: string): string {
+  return name.replace(/\0/g, "").replace(/[/\\]/g, "-").replace(/\.\./g, "-").slice(0, 100);
+}

package/templates/_base/src/lib/startup.ts

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { log } from "./logger.js";
+
+export function parseArgs(): { port: number } {
+  const args = process.argv.slice(2);
+  let port = 4100;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--port" && args[i + 1]) {
+      port = parseInt(args[++i], 10);
+    }
+  }
+
+  return { port };
+}
+
+export function loadConfig(): { model?: string; compactionMessage?: string } {
+  try {
+    return JSON.parse(readFileSync(resolve("home/.config/volute.json"), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function loadFile(path: string): string {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function loadSystemPrompt(): string {
+  const soulPath = resolve("home/SOUL.md");
+  const memoryPath = resolve("home/MEMORY.md");
+  const volutePath = resolve("home/VOLUTE.md");
+
+  const soul = loadFile(soulPath);
+  if (!soul) {
+    console.error(`Could not read soul file: ${soulPath}`);
+    process.exit(1);
+  }
+
+  const memory = loadFile(memoryPath);
+  const volute = loadFile(volutePath);
+
+  const promptParts = [soul];
+  if (volute) promptParts.push(volute);
+  if (memory) promptParts.push(`## Memory\n\n${memory}`);
+  return promptParts.join("\n\n---\n\n");
+}
+
+export function loadPackageInfo(): { name: string; version: string } {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve("package.json"), "utf-8"));
+    return { name: pkg.name || "unknown", version: pkg.version || "0.0.0" };
+  } catch {
+    return { name: "unknown", version: "0.0.0" };
+  }
+}
+
+export function handleMergeContext(sendMessage: (content: string) => void): boolean {
+  const mergedPath = resolve(".volute/merged.json");
+  if (!existsSync(mergedPath)) return false;
+
+  try {
+    const merged = JSON.parse(readFileSync(mergedPath, "utf-8"));
+    unlinkSync(mergedPath);
+
+    const parts = [
+      `[system] Variant "${merged.name}" has been merged and you have been restarted.`,
+    ];
+    if (merged.summary) parts.push(`Changes: ${merged.summary}`);
+    if (merged.justification) parts.push(`Why: ${merged.justification}`);
+    if (merged.memory) parts.push(`Context: ${merged.memory}`);
+
+    sendMessage(parts.join("\n"));
+    log("server", `sent post-merge orientation for variant: ${merged.name}`);
+    return true;
+  } catch (e) {
+    log("server", "failed to process merged.json:", e);
+    return false;
+  }
+}
+
+export async function handleStartupContext(sendMessage: (content: string) => void): Promise<void> {
+  const scriptPath = resolve("home/.config/hooks/startup-context.sh");
+  if (!existsSync(scriptPath)) return;
+
+  try {
+    const stdout = await new Promise<string>((resolve, reject) => {
+      const child = spawn("bash", [scriptPath], { timeout: 5000 });
+      let out = "";
+      child.stdout.on("data", (d: Buffer) => {
+        out += d.toString();
+      });
+      child.stdin.end(JSON.stringify({ source: "startup" }));
+      child.on("close", (code) =>
+        code === 0 ? resolve(out) : reject(new Error(`exit code ${code}`)),
+      );
+      child.on("error", reject);
+    });
+
+    // Try to parse as JSON hook output
+    let context: string | null = null;
+    try {
+      const parsed = JSON.parse(stdout);
+      context = parsed?.hookSpecificOutput?.additionalContext ?? null;
+    } catch {
+      // Fall back to plain text
+      context = stdout.trim();
+    }
+
+    if (context) {
+      sendMessage(`[system] ${context}`);
+      log("server", "sent startup context");
+    }
+  } catch (e) {
+    log("server", "failed to run startup-context.sh:", e);
+  }
+}
+
+export function setupShutdown(): void {
+  function shutdown() {
+    log("server", "shutdown signal received");
+    process.exit(0);
+  }
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/templates/_base/src/lib/types.ts

@@ -9,6 +9,7 @@ export type ChannelMeta = {
   isDM?: boolean;
   channelName?: string;
   guildName?: string;
+  sessionName?: string;
 };
 
 export type VoluteRequest = {
@@ -22,3 +23,5 @@ export type VoluteEvent =
   | { type: "tool_use"; name: string; input: unknown }
   | { type: "tool_result"; output: string; is_error?: boolean }
   | { type: "done" };
+
+export type Listener = (event: VoluteEvent) => void;

package/templates/_base/src/lib/volute-server.ts

@@ -1,10 +1,11 @@
 import { createServer, type IncomingMessage, type Server } from "node:http";
 import { log } from "./logger.js";
+import { loadSessionConfig, resolveSession } from "./sessions.js";
 import type { ChannelMeta, VoluteContentPart, VoluteEvent, VoluteRequest } from "./types.js";
 
 export type VoluteAgent = {
   sendMessage: (content: string | VoluteContentPart[], meta?: ChannelMeta) => void;
-  onMessage: (listener: (event: VoluteEvent) => void) => () => void;
+  onMessage: (listener: (event: VoluteEvent) => void, sessionName?: string) => () => void;
 };
 
 function readBody(req: IncomingMessage): Promise<string> {
@@ -21,6 +22,7 @@ export function createVoluteServer(options: {
   port: number;
   name: string;
   version: string;
+  sessionsConfigPath?: string;
 }): Server {
   const { agent, port, name, version } = options;
 
@@ -37,6 +39,19 @@ export function createVoluteServer(options: {
       try {
         const body = JSON.parse(await readBody(req)) as VoluteRequest;
 
+        // Resolve session from routing config (re-read on each request for hot-reload)
+        let sessionName = "main";
+        if (options.sessionsConfigPath) {
+          const sessionConfig = loadSessionConfig(options.sessionsConfigPath);
+          sessionName = resolveSession(sessionConfig, {
+            channel: body.channel,
+            sender: body.sender,
+          });
+        }
+        if (sessionName === "$new") {
+          sessionName = `new-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        }
+
         res.writeHead(200, {
           "Content-Type": "application/x-ndjson",
           "Cache-Control": "no-cache",
@@ -53,7 +68,7 @@ export function createVoluteServer(options: {
           } catch {
             removeListener();
           }
-        });
+        }, sessionName);
 
         res.on("close", () => {
           removeListener();
@@ -66,6 +81,7 @@ export function createVoluteServer(options: {
           isDM: body.isDM,
           channelName: body.channelName,
           guildName: body.guildName,
+          sessionName,
         });
       } catch {
         res.writeHead(400);

package/templates/agent-sdk/.init/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.config/hooks/startup-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/agent-sdk/.init/.config/sessions.json

@@ -0,0 +1,4 @@
+{
+  "rules": [],
+  "default": "main"
+}

package/templates/agent-sdk/.init/CLAUDE.md

@@ -24,13 +24,14 @@ These files define who you are and are loaded into your system prompt on startup
 Two-tier memory, both managed via file tools:
 
 - **`MEMORY.md`** — Long-term knowledge, key decisions, learned preferences. Loaded into your system prompt on every startup. Update when you learn something worth keeping permanently.
-- **`memory/YYYY-MM-DD.md`** — Daily logs for session-level context. The two most recent logs are included in your system prompt. Update throughout the day as you work.
-- Periodically consolidate old daily log entries into `MEMORY.md` and clean up the daily logs.
+- **`memory/journal/YYYY-MM-DD.md`** — Daily journal entries for session-level context. Update throughout the day as you work. Journals are permanent records.
+- Periodically consolidate journal entries into `MEMORY.md` to promote lasting insights.
 
 See the **memory** skill for detailed guidance on consolidation and when to update.
 
 ## Sessions
 
+- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/sessions.json`.
 - Your conversation may be **resumed** from a previous session — orient yourself by reading recent daily logs if needed.
 - On a **fresh session**, check `MEMORY.md` and recent daily logs in `memory/` to recall context.
 - On **compaction**, update today's daily log to preserve context before the conversation is trimmed.

package/templates/agent-sdk/package.json.tmpl

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.34",
     "tsx": "^4.0.0"
   },
   "devDependencies": {

package/templates/agent-sdk/src/agent.ts

@@ -0,0 +1,101 @@
+import { createSessionManager } from "./lib/agent-sessions.js";
+import { formatPrefix } from "./lib/format-prefix.js";
+import { createAutoCommitHook } from "./lib/hooks/auto-commit.js";
+import { createIdentityReloadHook } from "./lib/hooks/identity-reload.js";
+import { logMessage } from "./lib/logger.js";
+import type { ChannelMeta, Listener, VoluteContentPart } from "./lib/types.js";
+
+export function createAgent(options: {
+  systemPrompt: string;
+  cwd: string;
+  abortController: AbortController;
+  model?: string;
+  sessionsDir: string;
+  compactionMessage?: string;
+  onIdentityReload?: () => Promise<void>;
+}) {
+  const autoCommit = createAutoCommitHook(options.cwd);
+  const identityReload = createIdentityReloadHook(options.cwd);
+
+  const sessionManager = createSessionManager({
+    systemPrompt: options.systemPrompt,
+    cwd: options.cwd,
+    abortController: options.abortController,
+    model: options.model,
+    sessionsDir: options.sessionsDir,
+    compactionMessage: options.compactionMessage,
+    postToolUseHooks: [{ matcher: "Edit|Write", hooks: [autoCommit.hook, identityReload.hook] }],
+    onTurnDone: () => {
+      if (identityReload.needsReload()) {
+        options.onIdentityReload?.();
+      }
+    },
+  });
+
+  function sendMessage(content: string | VoluteContentPart[], meta?: ChannelMeta) {
+    const sessionName = meta?.sessionName ?? "main";
+    const session = sessionManager.getOrCreateSession(sessionName);
+
+    const text =
+      typeof content === "string"
+        ? content
+        : content.map((p) => (p.type === "text" ? p.text : `[${p.type}]`)).join(" ");
+    logMessage("in", text, meta?.channel);
+
+    const time = new Date().toLocaleString();
+    const prefix = formatPrefix(meta, time);
+
+    let sdkContent: (
+      | { type: "text"; text: string }
+      | {
+          type: "image";
+          source: {
+            type: "base64";
+            media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+            data: string;
+          };
+        }
+    )[];
+
+    if (typeof content === "string") {
+      sdkContent = [{ type: "text" as const, text: prefix + content }];
+    } else {
+      const hasText = content.some((p) => p.type === "text");
+      sdkContent = content.map((part, i) => {
+        if (part.type === "text") {
+          return { type: "text" as const, text: (i === 0 ? prefix : "") + part.text };
+        }
+        return {
+          type: "image" as const,
+          source: {
+            type: "base64" as const,
+            media_type: part.media_type as "image/jpeg" | "image/png" | "image/gif" | "image/webp",
+            data: part.data,
+          },
+        };
+      });
+      if (prefix && !hasText) {
+        sdkContent.unshift({ type: "text" as const, text: prefix.trimEnd() });
+      }
+    }
+
+    session.channel.push({
+      type: "user",
+      session_id: "",
+      message: {
+        role: "user",
+        content: sdkContent,
+      },
+      parent_tool_use_id: null,
+    });
+  }
+
+  function onMessage(listener: Listener, sessionName?: string): () => void {
+    const name = sessionName ?? "main";
+    const session = sessionManager.getOrCreateSession(name);
+    session.listeners.add(listener);
+    return () => session.listeners.delete(listener);
+  }
+
+  return { sendMessage, onMessage, waitForCommits: autoCommit.waitForCommits };
+}