v0.5.0

bun.lock

@@ -5,7 +5,7 @@
     "": {
       "name": "boxbrain",
       "dependencies": {
-        "identitydb": "^0.3.0",
+        "identitydb": "^0.5.0",
       },
       "devDependencies": {
         "@types/bun": "latest",
@@ -249,7 +249,7 @@
 
     "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
 
-    "identitydb": ["identitydb@0.3.0", "", { "dependencies": { "kysely": "^0.28.8", "mysql2": "^3.15.3", "pg": "^8.16.0" } }, "sha512-OvJkxm3Sa5YEnQum8piQ5UnQ0P5yiDYS5vJKfaMPLqHkfkgrgE3jDno4/k8xBUeHkt8BkB7HH1Wj1b/FxPBAkg=="],
+    "identitydb": ["identitydb@0.5.0", "", { "dependencies": { "kysely": "^0.28.8", "mysql2": "^3.15.3", "pg": "^8.16.0" } }, "sha512-3cp14fb5nDKFakRqHdJrOBOgpDWLlvJ/K2q8405muAfqcJja9ds2tS9ksoaEiMgGU5r+mIz6lADZ3DYNpGqHVQ=="],
 
     "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "boxbrain",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Human-like persona harness framework powered by LLMs and IdentityDB.",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "prepublishOnly": "bun run check && bun run test && bun run build && bun run pack:check"
   },
   "dependencies": {
-    "identitydb": "^0.3.0"
+    "identitydb": "^0.5.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

src/conversation.ts

@@ -20,14 +20,16 @@ export function formatMessageHistory(input: {
     .join("\n");
 }
 
-export function conversationInstruction(): string {
+export function conversationInstruction(baseSystemPrompt?: string): string {
-  return [
+  const parts = [
+    ...(baseSystemPrompt === undefined ? [] : [baseSystemPrompt]),
     "You are controlling the persona, not a generic assistant.",
     "Use the send_message tool conceptually: return one or more outgoing messages.",
     "Unless the persona strongly prefers otherwise, keep each outgoing message to at most one sentence.",
     "Prefer short, natural, chat-like wording and allow splitting one thought into multiple messages.",
     'If mandatory memory says "기억이 없음", the persona may naturally wonder about missing context instead of pretending to remember.',
-  ].join("\n");
+  ];
+  return parts.join("\n");
 }
 
 export async function buildMandatoryConversationContext(input: {

src/persona.ts

@@ -10,7 +10,7 @@ import {
   startOfUtcDay,
   toIso,
 } from "./schedule";
-import { extractFact } from "identitydb";
+import { ExtractedFact, extractFacts } from "identitydb";
 import {
   buildMandatoryConversationContext,
   conversationInstruction,
@@ -68,6 +68,7 @@ export class Persona {
   private readonly mode: Mode;
   private readonly readyPromise: Promise<MemorySpace>;
   private availabilitySnapshot?: ScheduledAvailabilitySnapshot;
+  readonly baseSystemPrompt: string | undefined;
 
   constructor(
     displayName: string,
@@ -88,6 +89,7 @@ export class Persona {
       this.options = second ?? {};
     }
     this.memory = this.options.memory ?? new InMemoryMemoryStore();
+    this.baseSystemPrompt = this.options.baseSystemPrompt;
     this.readyPromise = this.initialize();
   }
 
@@ -247,7 +249,7 @@ export class Persona {
         mode: "reply",
         context,
         ...(userMessage === undefined ? {} : { userMessage }),
-        instruction: conversationInstruction(),
+        instruction: conversationInstruction(this.baseSystemPrompt),
       }),
     );
 
@@ -281,7 +283,7 @@ export class Persona {
                 now: toIso(input.datetime),
                 mode: "reply",
                 context: latestContext,
-                instruction: conversationInstruction(),
+                instruction: conversationInstruction(this.baseSystemPrompt),
               })),
           );
         }
@@ -320,7 +322,7 @@ export class Persona {
         now: toIso(input.datetime),
         mode: "start-conversation",
         context,
-        instruction: conversationInstruction(),
+        instruction: conversationInstruction(this.baseSystemPrompt),
       }),
     );
     await this.emit("persona.conversation.started", {
@@ -329,6 +331,20 @@ export class Persona {
     return draft;
   }
 
+  private extractedToDraft(fact: ExtractedFact, statement: string): FactDraft {
+    return {
+      statement: fact.statement ?? statement,
+      topics: [...fact.topics.map((t) => t.name), "sleepMemory"],
+      source: fact.source ?? "boxbrain.sleepMemory",
+      ...(typeof fact.confidence === "number"
+        ? { confidence: fact.confidence }
+        : {}),
+      ...(fact.metadata !== undefined && fact.metadata !== null
+        ? { metadata: fact.metadata as Record<string, unknown> }
+        : {}),
+    };
+  }
+
   async sleepMemory(input: {
     datetime: DateTimeInput;
     messageHistory: PersonaMessage[];
@@ -358,26 +374,17 @@ export class Persona {
         messages: input.messageHistory,
       }),
     ].join("\n");
-    const extracted = await extractFact(
+    const extractedFacts = (
-      statement,
+      await extractFacts(statement, this.options.models.factExtractor)
-      this.options.models.factExtractor,
+    ).map((fact) => this.extractedToDraft(fact, statement));
-    );
+
-    const draft: FactDraft = {
+    for (const fact of extractedFacts) {
-      statement: extracted.statement ?? statement,
+      await this.memory.addFact(persona.id, fact);
-      topics: [...extracted.topics.map((t) => t.name), "sleepMemory"],
+    }
-      source: extracted.source ?? "boxbrain.sleepMemory",
-      ...(typeof extracted.confidence === 'number'
-        ? { confidence: extracted.confidence }
-        : {}),
-      ...(extracted.metadata !== undefined && extracted.metadata !== null
-        ? { metadata: extracted.metadata as Record<string, unknown> }
-        : {}),
-    };
-    await this.memory.addFact(persona.id, draft);
     await this.emit("persona.memory.sleep.persisted", {
-      factCount: 1,
+      factCount: extractedFacts.length,
     });
-    return [draft];
+    return extractedFacts;
   }
 
   private async initialize(): Promise<MemorySpace> {
@@ -398,29 +405,24 @@ export class Persona {
     });
     if (this.options.models?.factExtractor) {
       const statement = `Persona: ${this.mode.displayName}\nSeed: ${this.mode.seedMessage}`;
-      const extracted = await extractFact(
+      const extracteds = (
-        statement,
+        await extractFacts(statement, this.options.models.factExtractor)
-        this.options.models.factExtractor,
+      ).map((fact) => this.extractedToDraft(fact, statement));
-      );
+
-      const draft: FactDraft = {
+      for (const fact of extracteds) {
-        statement: extracted.statement ?? statement,
+        await this.memory.addFact(space.id, fact);
-        topics: extracted.topics.map((t) => t.name),
+      }
-        source: extracted.source ?? "boxbrain.persona.initialization",
+
-        ...(typeof extracted.confidence === 'number'
-          ? { confidence: extracted.confidence }
-          : {}),
-        ...(extracted.metadata !== undefined && extracted.metadata !== null
-          ? { metadata: extracted.metadata as Record<string, unknown> }
-          : {}),
-      };
-      await this.memory.addFact(space.id, draft);
       await this.emit(
         "persona.initialized",
-        { displayName: space.displayName, factCount: 1 },
+        { displayName: space.displayName, factCount: extracteds.length },
         space.id,
       );
     } else {
-      const fact = defaultInitialFact(this.mode.displayName, this.mode.seedMessage);
+      const fact = defaultInitialFact(
+        this.mode.displayName,
+        this.mode.seedMessage,
+      );
       await this.memory.addFact(space.id, fact);
       await this.emit(
         "persona.initialized",

src/types.ts

@@ -160,6 +160,7 @@ export interface PersonaOptions {
   models?: PersonaModels;
   debug?: DebugHook;
   now?: DateTimeInput;
+  baseSystemPrompt?: string;
 }
 
 export interface BoxBrainMemoryStore {

tests/conversation.test.ts

@@ -124,4 +124,30 @@ describe('Conversation API', () => {
     expect(mode).toBe('start-conversation');
     expect(started.messages).toEqual(['오늘 좀 조용하네.']);
   });
+
+  it('includes baseSystemPrompt at the start of the instruction when provided', async () => {
+    const memory = new InMemoryMemoryStore();
+    let captured: ReplyGenerationInput | undefined;
+    const persona = new Persona('Mina', 'Mina likes quiet cafes.', {
+      memory,
+      now: '2026-05-01T10:00:00.000Z',
+      baseSystemPrompt: 'You are a helpful assistant. Always be kind.',
+      models: {
+        conversation: {
+          async generateReply(input) {
+            captured = input;
+            return { messages: ['Hello!'] };
+          },
+        },
+      },
+    });
+    await persona.ready();
+
+    await persona.sendMessage({
+      datetime: '2026-05-01T12:00:00.000Z',
+      messageHistory: [{ sender: 'user', time: '2026-05-01T12:00:00.000Z', content: 'Hi' }],
+    });
+
+    expect(captured?.instruction.startsWith('You are a helpful assistant. Always be kind.')).toBe(true);
+  });
 });

tests/persona.test.ts

@@ -12,11 +12,11 @@ describe('Persona initialization', () => {
       models: {
         factExtractor: {
           async extract(input) {
-            return {
+            return [{
               statement: 'Mina likes quiet cafes.',
               topics: [{ name: 'persona' }, { name: 'Mina' }],
               source: 'test',
-            };
+            }];
           },
         },
       },
@@ -29,6 +29,18 @@ describe('Persona initialization', () => {
     expect(debug).toContain('persona.initialized');
   });
 
+  it('exposes baseSystemPrompt on the persona instance when provided', async () => {
+    const memory = new InMemoryMemoryStore();
+    const persona = new Persona('Hana', 'Hana is a cheerful barista.', {
+      memory,
+      now: '2026-05-01T10:00:00.000Z',
+      baseSystemPrompt: 'You are a helpful assistant. Always be kind.',
+    });
+
+    await persona.ready();
+    expect(persona.baseSystemPrompt).toBe('You are a helpful assistant. Always be kind.');
+  });
+
   it('loads an existing persona space by space id without creating another space', async () => {
     const memory = new InMemoryMemoryStore();
     const created = new Persona('Joon', 'Joon is a freelance designer.', { memory, now: '2026-05-01T10:00:00.000Z' });

tests/sleep-memory.test.ts

@@ -11,15 +11,15 @@ describe('sleepMemory', () => {
         factExtractor: {
           async extract(input) {
             if (input.includes('Seed:')) {
-              return { statement: 'Mina remembers stable details.', topics: [{ name: 'persona' }, { name: 'Mina' }] };
+              return [{ statement: 'Mina remembers stable details.', topics: [{ name: 'persona' }, { name: 'Mina' }] }];
             }
             expect(input).toContain('user@2026-05-01T15:00:00.000Z: 나는 타입스크립트를 2025년부터 시작했어');
             expect(input).toContain('Objectivize');
-            return {
+            return [{
               statement: 'The user started TypeScript in 2025.',
               topics: [{ name: 'user' }, { name: 'TypeScript' }, { name: '2025' }],
               confidence: 0.9,
-            };
+            }];
           },
         },
       },