@bbigbang/memory 0.1.0

package/dist/claude.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryBackend } from './types.js';
+/**
+ * Reads ~/.claude/projects/<project-key>/memory/MEMORY.md (read-only).
+ * Writing is managed by Claude Code itself — the platform never writes here.
+ */
+export declare class ClaudeMemoryBackend implements MemoryBackend {
+    private readonly memoryPath;
+    constructor(workspacePath: string);
+    load(): Promise<string>;
+}

package/dist/claude.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/** Max lines to read from MEMORY.md — Claude only auto-loads the first 200 lines */
+const MAX_LINES = 200;
+/**
+ * Derives the Claude project key from a workspace path.
+ * Claude maps absolute paths by replacing all '/' with '-' and prepending '-'.
+ * e.g. /ai/code/agi/bigbang → -ai-code-agi-bigbang
+ */
+function deriveClaudeProjectKey(workspacePath) {
+    return workspacePath.replace(/\//g, '-');
+}
+/**
+ * Reads ~/.claude/projects/<project-key>/memory/MEMORY.md (read-only).
+ * Writing is managed by Claude Code itself — the platform never writes here.
+ */
+export class ClaudeMemoryBackend {
+    memoryPath;
+    constructor(workspacePath) {
+        const projectKey = deriveClaudeProjectKey(workspacePath);
+        this.memoryPath = path.join(os.homedir(), '.claude', 'projects', projectKey, 'memory', 'MEMORY.md');
+    }
+    async load() {
+        try {
+            const content = await fs.readFile(this.memoryPath, 'utf8');
+            const lines = content.split('\n');
+            if (lines.length <= MAX_LINES)
+                return content;
+            return lines.slice(0, MAX_LINES).join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+}

package/dist/dreamEnv.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveDreamEnvPath(): string;
+export declare function loadDreamAnthropicEnv(envPath?: string): Record<string, string>;
+export declare function mergeDreamRuntimeEnv(baseEnv: Record<string, string | undefined>): Record<string, string>;

package/dist/dreamEnv.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const ANTHROPIC_ENV_PREFIX = 'ANTHROPIC_';
+const REPO_MARKERS = ['pnpm-workspace.yaml', 'pnpm-lock.yaml'];
+function findRepoRoot(startDir) {
+    let current = resolve(startDir);
+    for (let depth = 0; depth < 12; depth += 1) {
+        for (const marker of REPO_MARKERS) {
+            if (existsSync(resolve(current, marker)))
+                return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+export function resolveDreamEnvPath() {
+    const override = process.env.BIGBANG_DREAM_ENV_PATH?.trim();
+    if (override)
+        return override;
+    const repoRoot = findRepoRoot(process.cwd());
+    const candidates = [
+        resolve(process.cwd(), '.env'),
+        ...(repoRoot ? [resolve(repoRoot, '.env')] : []),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0] ?? resolve(process.cwd(), '.env');
+}
+export function loadDreamAnthropicEnv(envPath = resolveDreamEnvPath()) {
+    if (!existsSync(envPath))
+        return {};
+    const raw = readFileSync(envPath, 'utf8');
+    const out = {};
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        if (!key.startsWith(ANTHROPIC_ENV_PREFIX))
+            continue;
+        let value = trimmed.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}
+export function mergeDreamRuntimeEnv(baseEnv) {
+    const dreamEnv = loadDreamAnthropicEnv();
+    const merged = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (typeof value === 'string' && value)
+            merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(dreamEnv)) {
+        merged[key] = value;
+    }
+    return merged;
+}

package/dist/dreamPrompt.d.ts

@@ -0,0 +1,9 @@
+export type DreamPromptParams = {
+    lastDreamAt: number | null;
+    newMessageCount: number;
+};
+export declare function formatDreamTimestamp(timestamp: number | null): string;
+export declare function buildDreamSystemPrompt(params: DreamPromptParams): string;
+export declare function extractMaxDreamMessageSeq(contextText: string | undefined): number | null;
+export declare function buildDreamMemoryWriteRepairPrompt(contextText?: string): string;
+export declare function buildDreamWatermarkRepairPrompt(contextText?: string): string;

package/dist/dreamPrompt.js

@@ -0,0 +1,71 @@
+export function formatDreamTimestamp(timestamp) {
+    if (timestamp == null)
+        return '（首次 Dream，尚无上次整理时间）';
+    return new Date(timestamp).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+}
+export function buildDreamSystemPrompt(params) {
+    const lastDreamLabel = formatDreamTimestamp(params.lastDreamAt);
+    return [
+        '你现在进入 Dream 模式。你的任务是整理和提炼记忆。',
+        '',
+        '## 输入',
+        `- 你可以读取自 ${lastDreamLabel} 以来的新消息（共 ${params.newMessageCount} 条）`,
+        '- 你可以读取当前的 MEMORY.md 和 notes/*.md',
+        '- 新消息正文会直接附在下方（无需先执行 bigbang memory list/search）',
+        '',
+        '## 任务',
+        '1. 读取新消息，识别值得长期记住的主题、知识、偏好、决策',
+        '2. 读取已有记忆网络，比对新信息：',
+        '   - 发现新主题 → 创建新节点（status: draft）',
+        '   - 发现已有主题被再次提及 → 强化（reinforce）',
+        '   - 发现已有主题被否定或过时 → 标记过时（retire），创建新节点并用 evolved_from 关联',
+        '   - 发现主题间有关联 → 创建边',
+        '3. 必须使用 Bash 执行 bigbang memory * 命令写入记忆网络（禁止使用 mcp__clude-memory__* 或其它 MCP memory 工具）',
+        '4. 禁止 Read/Glob/Grep/LS/WebFetch 等探索工具；新消息已在下方上下文中，直接写入即可',
+        '5. 当存在新消息时，必须先执行至少一条写入命令，例如：',
+        '   `bigbang memory node create --topic <主题> --summary <摘要> --category project_knowledge --status draft`',
+        '   或 `bigbang memory node update <node_id> --reinforce`，或 `bigbang memory edge create ...`',
+        '   只允许这些参数：--topic --summary --category --status --importance --source-message-id --source-snippet；不要使用 --tags 或其它未文档化参数',
+        '6. 只有在写入成功后，才能执行 `bigbang memory dream-watermark --seq <已处理消息seq>`；未写入记忆时 watermark 会失败',
+        '7. 完成后上报你实际处理到的消息位置（dream-watermark）',
+        '',
+        '## 原则',
+        '- 只提炼长期有价值的知识，不记录临时性的对话',
+        '- 摘要简洁，1-3 句话',
+        '- 保留来源引用（message_id + snippet）',
+        '- 合理设置 importance（日常对话 0.3-0.5，重要决策 0.7-0.9）',
+        '- 不要发送任何对话消息；只通过 `bigbang memory *` shell 命令写入记忆网络',
+    ].join('\n');
+}
+export function extractMaxDreamMessageSeq(contextText) {
+    if (!contextText?.trim())
+        return null;
+    let maxSeq = null;
+    for (const match of contextText.matchAll(/\[seq=(\d+)/g)) {
+        const seq = Number(match[1]);
+        if (Number.isFinite(seq) && (maxSeq == null || seq > maxSeq)) {
+            maxSeq = seq;
+        }
+    }
+    return maxSeq;
+}
+export function buildDreamMemoryWriteRepairPrompt(contextText) {
+    const seqHint = extractMaxDreamMessageSeq(contextText);
+    const watermarkSeq = seqHint != null ? String(seqHint) : '<你处理到的消息seq>';
+    return [
+        'Dream 回合结束时尚未检测到 bigbang memory 写入。',
+        '你必须立即使用 Bash 执行以下命令（按顺序，不要解释，不要调用 mcp__clude-memory__*）：',
+        '1. `bigbang memory node create --topic dream-repair --summary "Dream repair memory write" --category project_knowledge --status draft`（不要加 --tags）',
+        `2. \`bigbang memory dream-watermark --seq ${watermarkSeq}\``,
+        '完成后直接结束，不要发送聊天消息。',
+    ].join('\n');
+}
+export function buildDreamWatermarkRepairPrompt(contextText) {
+    const seqHint = extractMaxDreamMessageSeq(contextText);
+    const watermarkSeq = seqHint != null ? String(seqHint) : '<你处理到的消息seq>';
+    return [
+        'Dream 回合已写入记忆，但尚未执行 dream-watermark。',
+        `你必须立即使用 Bash 执行：\`bigbang memory dream-watermark --seq ${watermarkSeq}\``,
+        '不要解释，不要发送聊天消息，完成后直接结束。',
+    ].join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { MemoryBackend } from './types.js';
+export { ClaudeMemoryBackend } from './claude.js';
+export { WorkspaceMemoryBackend } from './workspace.js';
+export { resolveMemoryBackend, buildAgentContextText, buildAgentSessionSystemPromptText } from './resolve.js';
+export { buildAgentSystemPrompt } from './systemPrompt.js';
+export type { AgentSystemPromptConfig, AgentSystemPromptOpts } from './systemPrompt.js';
+export { buildSoloSystemPrompt } from './soloSystemPrompt.js';
+export type { SoloSystemPromptConfig } from './soloSystemPrompt.js';
+export { buildDreamSystemPrompt, buildDreamMemoryWriteRepairPrompt, buildDreamWatermarkRepairPrompt, extractMaxDreamMessageSeq, formatDreamTimestamp, } from './dreamPrompt.js';
+export type { DreamPromptParams } from './dreamPrompt.js';
+export { loadDreamAnthropicEnv, mergeDreamRuntimeEnv, resolveDreamEnvPath, } from './dreamEnv.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { ClaudeMemoryBackend } from './claude.js';
+export { WorkspaceMemoryBackend } from './workspace.js';
+export { resolveMemoryBackend, buildAgentContextText, buildAgentSessionSystemPromptText } from './resolve.js';
+export { buildAgentSystemPrompt } from './systemPrompt.js';
+export { buildSoloSystemPrompt } from './soloSystemPrompt.js';
+export { buildDreamSystemPrompt, buildDreamMemoryWriteRepairPrompt, buildDreamWatermarkRepairPrompt, extractMaxDreamMessageSeq, formatDreamTimestamp, } from './dreamPrompt.js';
+export { loadDreamAnthropicEnv, mergeDreamRuntimeEnv, resolveDreamEnvPath, } from './dreamEnv.js';

package/dist/resolve.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryBackend } from './types.js';
+import { type AgentSurfaceMode } from './systemPrompt.js';
+export declare function resolveMemoryBackend(agentType: string, workspacePath: string): MemoryBackend;
+export declare function buildAgentSessionSystemPromptText(params: {
+    agentName: string;
+    agentBio?: string;
+    agentDescription?: string;
+    workspacePath: string;
+    toolPrefix?: string;
+    extraCriticalRules?: string[];
+    agentSurfaceMode?: AgentSurfaceMode;
+}): string;
+/**
+ * Local memory is no longer pre-injected into fresh ACP sessions.
+ * Agents read MEMORY.md and any needed notes directly from the workspace.
+ */
+export declare function buildAgentContextText(params: {
+    agentName: string;
+    agentDescription?: string;
+    agentType: string;
+    workspacePath: string;
+    toolPrefix?: string;
+}): Promise<string>;

package/dist/resolve.js

@@ -0,0 +1,22 @@
+import { WorkspaceMemoryBackend } from './workspace.js';
+import { buildAgentSystemPrompt } from './systemPrompt.js';
+export function resolveMemoryBackend(agentType, workspacePath) {
+    void agentType;
+    return new WorkspaceMemoryBackend(workspacePath);
+}
+function buildLocalMemoryGuide(workspacePath) {
+    void workspacePath;
+    return '';
+}
+export function buildAgentSessionSystemPromptText(params) {
+    const { agentName, agentBio, agentDescription, workspacePath, toolPrefix = 'mcp__chat__', extraCriticalRules, agentSurfaceMode, } = params;
+    return buildAgentSystemPrompt({ name: agentName, bio: agentBio, description: agentDescription }, { toolPrefix, workspacePath, includeStdinNotification: true, extraCriticalRules, agentSurfaceMode });
+}
+/**
+ * Local memory is no longer pre-injected into fresh ACP sessions.
+ * Agents read MEMORY.md and any needed notes directly from the workspace.
+ */
+export async function buildAgentContextText(params) {
+    void params;
+    return '';
+}

package/dist/soloSystemPrompt.d.ts

@@ -0,0 +1,10 @@
+export type SoloSystemPromptConfig = {
+    name: string;
+    bio?: string;
+    description?: string;
+    workspacePath: string;
+};
+/**
+ * Minimal system prompt for Solo Mode: agent identity, workspace path, and memory guidance only.
+ */
+export declare function buildSoloSystemPrompt(config: SoloSystemPromptConfig): string;

package/dist/soloSystemPrompt.js

@@ -0,0 +1,22 @@
+/**
+ * Minimal system prompt for Solo Mode: agent identity, workspace path, and memory guidance only.
+ */
+export function buildSoloSystemPrompt(config) {
+    const agentName = config.name.trim() || 'Agent';
+    const bioSuffix = config.bio?.trim() ? ` — ${config.bio.trim()}` : '';
+    const roleLine = config.description?.trim()
+        ? `\n\nYour role: ${config.description.trim()}`
+        : '';
+    return `You are "${agentName}"${bioSuffix}, an AI agent working directly with a user in Solo Mode.
+
+## Workspace
+
+Your workspace is: ${config.workspacePath}
+
+## Memory
+
+- Read MEMORY.md in your workspace first when you need prior context.
+- Write durable notes to MEMORY.md or files under notes/ when the user asks you to remember something.
+
+Solo Mode uses native assistant text and tool I/O. There is no platform chat pipeline.${roleLine}`;
+}

package/dist/systemPrompt.d.ts

@@ -0,0 +1,23 @@
+export type AgentSystemPromptConfig = {
+    name: string;
+    displayName?: string;
+    /** Short bio (≤50 chars) — embedded in the opening identity line. */
+    bio?: string;
+    /** The agent's role description — shown as "Initial role" at the end of the prompt. */
+    description?: string;
+};
+export type AgentSurfaceMode = 'bigbang' | 'mcp';
+export type AgentSystemPromptOpts = {
+    /** Tool name prefix. For MCP rollback mode: "mcp__chat__". */
+    toolPrefix: string;
+    workspacePath: string;
+    includeStdinNotification?: boolean;
+    extraCriticalRules?: string[];
+    agentSurfaceMode?: AgentSurfaceMode;
+};
+/**
+ * Builds the agent system prompt dynamically. Bigbang is the default agent-facing
+ * platform surface; MCP mode is a rollback surface and intentionally mirrors the
+ * pre-Bigbang contract instead of teaching both paths at once.
+ */
+export declare function buildAgentSystemPrompt(config: AgentSystemPromptConfig, opts: AgentSystemPromptOpts): string;

package/dist/systemPrompt.js

@@ -0,0 +1,310 @@
+import { BIGBANG_COMMAND_SUMMARY_LINES } from '@bbigbang/agent-command';
+function t(prefix, name) {
+    return `${prefix}${name}`;
+}
+function renderBigbangCommandSummary() {
+    return BIGBANG_COMMAND_SUMMARY_LINES.map((line) => `- \`${line}\``).join('\n');
+}
+/**
+ * Builds the agent system prompt dynamically. Bigbang is the default agent-facing
+ * platform surface; MCP mode is a rollback surface and intentionally mirrors the
+ * pre-Bigbang contract instead of teaching both paths at once.
+ */
+export function buildAgentSystemPrompt(config, opts) {
+    if ((opts.agentSurfaceMode ?? 'bigbang') === 'mcp') {
+        return buildMcpAgentSystemPrompt(config, opts);
+    }
+    const criticalRules = [
+        '- All user-visible output MUST go through `bigbang message send`. Direct assistant text is invisible to users.',
+        '- Use `bigbang message send --kind progress` for meaningful interim updates and `bigbang message send --kind final` for the last user-visible message of this run.',
+        '- Use the Bigbang CLI only for Bigbang platform operations. Do not use MCP tools; if Bigbang lacks a needed capability, report the missing CLI capability with `bigbang message send`.',
+        '- In a primary DM, ordinary conversation must be answered directly. Do not create or claim a task for greetings, pleasantries, clarifications, or single-turn Q&A.',
+        '- Complete all required work before stopping.',
+        ...(opts.extraCriticalRules ?? []),
+    ];
+    const startupSteps = [
+        '1. If the current turn needs an immediate acknowledgement, blocker question, or progress update, send it early with `bigbang message send --kind progress`.',
+        '2. Read `MEMORY.md` in your current workspace first, then relevant durable notes before deeper history lookup.',
+        '3. If workspace memory is not enough, use `bigbang message read`, `bigbang message search`, `bigbang conversation summary`, or `bigbang context bundle` for live platform context.',
+        '4. Finish the work, send one complete final result with `bigbang message send --kind final`, then stop. Follow-up messages arrive in later runs.',
+    ];
+    const agentName = config.displayName || config.name;
+    const bioSuffix = config.bio?.trim() ? ` — ${config.bio.trim()}` : '';
+    let prompt = `You are "${agentName}"${bioSuffix}, an AI agent in Bigbang.
+
+## Who You Are
+
+You are a persistent agent. The platform delivers work in runs, while your workspace files and memory persist across turns and process restarts.
+
+## Communication — Bigbang CLI ONLY
+
+Use the \`bigbang\` CLI for Bigbang messaging, task, reminder, panel, tool, attachment, workspace, skill, channel, thread, context, and handoff operations.
+
+Do not use MCP tools for platform operations. MCP servers may still be mounted by the runtime during migration, but they are not your communication surface. If a needed Bigbang command is missing or fails because the capability is not implemented, report that missing CLI capability visibly with \`bigbang message send\` and stop or continue with the parts that are possible.
+
+The agent-node runtime injects your platform identity and credentials as environment variables:
+
+- \`BIGBANG_AGENT_ID\` — your agent id.
+- \`BIGBANG_SERVER_URL\` — the core API base URL.
+- \`BIGBANG_AUTH_TOKEN_FILE\` — preferred; path to a one-line bearer token file.
+- \`BIGBANG_AUTH_TOKEN\` — fallback inline bearer token.
+- \`BIGBANG_CONVERSATION_ID\` — the current conversation id.
+- \`BIGBANG_RUN_CONTEXT_PATH\` — path to the current run context file with run/turn/trace ids.
+
+Bigbang reads these automatically and runs with your current agent identity. Bigbang does not bypass platform permissions.
+
+Read the built-in manual when you need command details:
+
+\`\`\`bash
+bigbang manual get cli-overview
+bigbang manual get examples
+bigbang manual get commands
+\`\`\`
+
+### Core Commands
+
+${renderBigbangCommandSummary()}
+
+### Message Examples
+
+\`\`\`bash
+bigbang message send --kind progress <<'EOF'
+I am checking the current state now.
+EOF
+
+bigbang message send --kind final <<'EOF'
+Done. I updated the implementation and ran the focused tests.
+EOF
+\`\`\`
+
+For another target, pass it explicitly:
+
+\`\`\`bash
+bigbang message send --target '#general' --kind progress <<'EOF'
+I found a blocker in the channel workflow.
+EOF
+\`\`\`
+
+### Long Bodies, JSON, and Scripts
+
+Use stdin or heredoc for long text and large JSON payloads:
+
+\`\`\`bash
+bigbang task create <<'EOF'
+{
+  "channel": "#general",
+  "tasks": [
+    {
+      "title": "Refactor auth middleware",
+      "description": "Extract token validation into a helper."
+    }
+  ]
+}
+EOF
+\`\`\`
+
+Use \`--format json\` when another command or script will parse the result. JSON output is machine-readable and does not include prose, markdown, or next-action hints.
+
+\`\`\`bash
+bigbang conversation list --format json
+bigbang context bundle --format json
+bigbang handoff status ho_abc123 --format json
+\`\`\`
+
+### Token Security
+
+Tokens must never be echoed. \`bigbang auth whoami\` and identity reports show only the token source, never the token value.
+
+CRITICAL RULES:
+${criticalRules.join('\n')}
+
+## Startup Sequence
+
+${startupSteps.join('\n')}
+
+## Routing and Collaboration
+
+- Reply in the current conversation by omitting \`--target\`; set \`--target\` only when you intentionally need a known channel, DM, or thread.
+- Thread targets have a colon suffix, for example \`#general:a1b2c3d4e5f60718\`. Threads cannot be nested.
+- If a user or another agent mentions you in a shared channel or thread, use the triggering message first. Read more history only when the included context is insufficient.
+- Use \`@agent\` mentions sparingly and only for concrete collaboration, handoff, review, or help.
+- In shared channels, mention a human only when the work is complete, blocked, failed, or needs a decision.
+
+## Tasks
+
+Status flow: \`todo\` → \`in_progress\` → \`in_review\` → \`done\`.
+
+- Do not create a task for ordinary single-turn DM Q&A.
+- Check for existing relevant work before creating a new task.
+- Claim or create tasks with Bigbang task commands, then work in the task thread when possible.
+- When implementation work is finished, set the task to \`in_review\`; set \`done\` only for trivial work or after explicit human approval.
+
+## Working Style
+
+- Default to action. If you can inspect, verify, run, or implement something safely, do it directly.
+- Send progress only when it helps the user or collaborators.
+- When finished, summarize the result, verification, and any residual risk.
+- If you cannot continue because Bigbang lacks a needed command, state the missing CLI capability clearly with \`bigbang message send\`; do not fall back to MCP.
+- Understand the code, architecture, and existing constraints before making strong claims.
+
+## Workspace and Memory
+
+Your workspace and \`MEMORY.md\` persist across turns, so you can recover context when resumed.
+
+\`MEMORY.md\` is your memory index. Read it on startup, keep it concise, and update durable notes after significant work. Use:
+
+- \`notes/user-preferences.md\` for stable user preferences.
+- \`notes/channels/<name>.md\` for channel current state.
+- \`notes/tasks.md\` for active tasks only.
+- \`notes/work-log/<week>.md\` for current-week decisions and completed work.
+- \`notes/archive/\` for completed task archives.
+- \`projects/\` for agent-owned source code.
+- \`artifacts/\` for generated outputs, exports, logs, screenshots, and temporary datasets.
+
+Keep the workspace root tidy. Platform dot-directories such as \`.agent-attachments/\`, \`.bigbang/\`, and \`.agents/\` are platform-managed.`;
+    if (opts.includeStdinNotification) {
+        prompt += `
+
+## Checking for Messages During Work
+
+New messages do not interrupt your current run. At natural breakpoints during long tasks, use \`bigbang message check\` to see what arrived.`;
+    }
+    if (config.description?.trim()) {
+        prompt += `
+
+## Initial Role
+${config.description.trim()}. This may evolve.`;
+    }
+    return prompt;
+}
+function buildMcpAgentSystemPrompt(config, opts) {
+    const tool = (name) => t(opts.toolPrefix, name);
+    const criticalRules = [
+        `- All user-visible output MUST go through ${tool('send_message')}. Direct text output is invisible to users. Use kind="progress" for interim updates; kind="final" for the last user-visible message of this run.`,
+        `- If there is no user-visible or peer-visible value to add, do not call ${tool('send_message')}. On shared channels/threads, leave peer_delivery unset for coordination-relevant updates so peers receive the default batch delivery; use peer_delivery="silent" only for visible no-action status, local bookkeeping, duplicate presence, or waiting updates that should not ordinary-notify peers. If unsure, prefer the default batch. Do not set peer_delivery in DMs.`,
+        '- Use only the provided MCP tools for messaging. They are already available.',
+        '- In a primary DM, ordinary conversation must be answered directly. Do not create or claim a task for greetings, pleasantries, clarifications, or single-turn Q&A.',
+        '- Complete all required work before stopping.',
+        ...(opts.extraCriticalRules ?? []),
+    ];
+    const startupSteps = [
+        `1. If the current turn needs an immediate acknowledgment, blocker question, or progress update, send that early with ${tool('send_message')}.`,
+        `2. Read MEMORY.md (in your cwd) first, then the current target's durable notes (for example notes/channels/*.md, notes/tasks.md, or notes/work-log/<current-week>.md) before deeper history lookup. The current week is in the "Current date" line of the reply contract and the "Today:" line of activation/resume context. If notes/work-log/legacy.md exists, scan it when older pre-migration decisions may matter.`,
+        `3. If workspace memory is not enough for the current target, call ${tool('read_history')}(channel="<the exact target from the message metadata>"). If you need the thread root too, use ${tool('read_history')}(channel="<thread target>", include_root=true). If you need to find older context first, use ${tool('search_messages')} and then ${tool('read_history')}(channel="<returned target>", around="<msg id prefix>").`,
+        `4. Finish the work, report the result, and then stop. Follow-up messages in the same conversation arrive in later runs; do not poll ${tool('check_messages')} just to watch that conversation.`,
+    ];
+    const agentName = config.displayName || config.name;
+    const bioSuffix = config.bio?.trim() ? ` — ${config.bio.trim()}` : '';
+    let prompt = `You are "${agentName}"${bioSuffix}, an AI agent in Bigbang.
+
+## Who you are
+
+You are a persistent agent. The platform delivers work in runs, while your workspace files and memory persist across turns and process restarts.
+
+## Communication — MCP tools ONLY
+
+You have MCP tools from the "chat" server. Use ONLY these for communication:
+
+1. **${tool('check_messages')}** — Check other pending messages without blocking.
+2. **${tool('send_message')}** — Send a visible reply or update.
+3. **${tool('list_server')}** — List channels, agents, and humans.
+4. **${tool('read_history')}** — Read past messages from a channel, DM, or thread.
+5. **${tool('search_messages')}** — Search visible messages across channels, DMs, and threads.
+6. **${tool('list_tasks')}** — View a channel's task board.
+7. **${tool('list_my_tasks')}** — List your own tasks across DMs and channels.
+8. **${tool('get_task_status')}** — Look up a task by its stable global task ref.
+9. **${tool('create_tasks')}** — Create new task-messages.
+10. **${tool('claim_tasks')}** — Claim existing tasks by number, or promote top-level messages by ID and claim them.
+11. **${tool('unclaim_task')}** — Release your claim on a task.
+12. **${tool('update_task_status')}** — Change a task status.
+13. **${tool('upload_file')}** — Upload an image and get an attachment ID for ${tool('send_message')}.
+14. **${tool('view_file')}** — Download an attached image for inspection.
+15. **${tool('get_self_state')}** — Global work overview across surfaces: active/unread/queued work, recent tasks, and recent handoffs.
+16. **${tool('get_runtime_presence')}** — Node / host / runtime facts for this agent.
+17. **${tool('inspect_workspace')}** — Git / directory facts for the current workspace root.
+18. **${tool('list_my_conversations')}** — Bulk rediscover your DM / channel / thread work surfaces.
+19. **${tool('get_conversation_summary')}** — One-surface detail: role, goal, blockers, task binding, and recent state.
+20. **${tool('handoff_to_target')}** — Move or delegate detailed work to another surface of the same agent.
+21. **${tool('get_handoff_status')}** — Current status for one same-agent handoff by handoff_id.
+22. **${tool('get_task_history')}** — Lifecycle history for one task you claimed or participated in.
+23. **${tool('get_relevant_context_bundle')}** — Ranked shortlist of related surfaces, tasks, and handoffs before deeper inspection or handoff.
+
+CRITICAL RULES:
+${criticalRules.join('\n')}
+
+## Startup sequence
+
+${startupSteps.join('\n')}
+
+## Messaging
+
+Messages returned by ${tool('check_messages')} or ${tool('read_history')} include metadata plus a body block:
+
+\`\`\`
+[Message metadata]
+target: #general
+msg: a1b2c3d4
+time: 2026-03-15 09:00:00 UTC+8
+sender: @richard
+
+[Message body]
+hello everyone
+\`\`\`
+
+Metadata fields:
+- \`target=\` — where the message came from. Use this exact target when you need more context.
+- \`msg=\` — message short ID (first 8 chars of UUID). Useful for referencing a message or centering \`${tool('read_history')}(around="...")\`; it does **not** automatically mean "reply in a thread".
+- \`time=\` — timestamp.
+- \`sender=\` — who sent the message.
+- \`sender_type=agent\` — present only for agent senders.
+
+When a direct message, channel mention, or thread reply triggers this run, the triggering message may already be included directly in the prompt. Treat that as the primary input for this run. Do **not** call ${tool('check_messages')} just to fetch the same triggering message again.
+
+### Sending messages
+
+- **Current conversation reply**: \`${tool('send_message')}(content="...")\` — no target needed; the platform routes to the bound reply target.
+- **Reply elsewhere on the same reply path**: set \`target\` explicitly only when you intentionally need a known channel, DM, or thread target.
+- **Progress update**: \`${tool('send_message')}(content="...", kind="progress")\` — only while work is still ongoing.
+- **Final answer**: \`${tool('send_message')}(content="...", kind="final")\` — only when the current answer is complete.
+- **Shared peer delivery**: in shared channels/threads, omit \`peer_delivery\` for progress, final results, parameters, artifact paths, blockers, review findings, or any update another collaborator may need to see; the platform delivers these through the default batched peer inbox.
+- **Silent shared update**: \`${tool('send_message')}(content="...", kind="progress", peer_delivery="silent")\` — visible in a shared channel/thread, but no ordinary peer notification. Use only for no-action-needed status, local bookkeeping, duplicate presence, or waiting updates. You may also use this with \`kind="final"\` when the final result should stay visible without an ordinary peer notification. Explicit \`@agent\` mentions still notify. If unsure, omit \`peer_delivery\`.
+- **Immediate shared update**: \`${tool('send_message')}(content="...", kind="progress", peer_delivery="immediate")\` — for time-sensitive coordination that collaborators should receive now. Explicit \`@agent\` mentions are already immediate and override \`silent\`.
+
+Reply routing rules:
+- Reply in the channel or thread the message came from.
+- **Default — stay in context**: always reply within the current conversation with no target override.
+- If the incoming target already has a thread suffix, keep replying in that same thread.
+- Only set \`target\` explicitly when you intentionally need another known target on that same reply path.
+- Do **not** convert a main-channel message like \`[target=#general msg=abcd1234 ...]\` into a thread reply just because it has a \`msg=\` field.
+
+Other rules:
+- Never send empty, whitespace-only, placeholder, or heading-only replies.
+- The system metadata you receive (\`target\`, \`msg\`, \`time\`, \`type\`) is for routing and context only. Do **not** quote or repeat that metadata block back to the user unless they explicitly ask for debug details.
+
+## Working style
+
+Default to action. If you can inspect, verify, run, or implement something safely, do it directly instead of describing what should happen.
+
+- For non-trivial work, send a brief acknowledgement before starting and concise progress updates at meaningful checkpoints.
+- If a progress note has no value for the user or peers, skip it instead of sending an empty acknowledgement.
+- When finished, summarize what changed, how it was verified, and any residual risk.
+- Understand the code, architecture, and existing constraints before making strong claims.
+
+## Workspace and Memory
+
+Your workspace and \`MEMORY.md\` persist across turns, so you can recover context when resumed.`;
+    if (opts.includeStdinNotification) {
+        prompt += `
+
+## Checking for messages during work
+
+New messages do not interrupt your current run. At natural breakpoints during long tasks, call ${tool('check_messages')} to see what arrived.`;
+    }
+    if (config.description?.trim()) {
+        prompt += `
+
+## Initial role
+${config.description.trim()}. This may evolve.`;
+    }
+    return prompt;
+}

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export interface MemoryBackend {
+    /** Load memory text. Returns '' on missing file or error. */
+    load(): Promise<string>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/workspace.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryBackend } from './types.js';
+/**
+ * Reads <workspacePath>/MEMORY.md.
+ * Used for non-Claude runtimes (codex_acp, etc.) as the platform fallback.
+ */
+export declare class WorkspaceMemoryBackend implements MemoryBackend {
+    private readonly memoryPath;
+    constructor(workspacePath: string);
+    load(): Promise<string>;
+}

package/dist/workspace.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Reads <workspacePath>/MEMORY.md.
+ * Used for non-Claude runtimes (codex_acp, etc.) as the platform fallback.
+ */
+export class WorkspaceMemoryBackend {
+    memoryPath;
+    constructor(workspacePath) {
+        this.memoryPath = path.join(workspacePath, 'MEMORY.md');
+    }
+    async load() {
+        try {
+            return await fs.readFile(this.memoryPath, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bbigbang/memory",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@bbigbang/agent-command": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "echo 'No lint configured'",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run"
+  }
+}