@animalabs/context-manager 0.1.0

package/src/strategies/index.ts

@@ -0,0 +1,2 @@
+export { PassthroughStrategy } from './passthrough.js';
+export { AutobiographicalStrategy } from './autobiographical.js';

package/src/strategies/knowledge.ts

@@ -0,0 +1,336 @@
+import type {
+  StoredMessage,
+  MessageStoreView,
+  KnowledgeConfig,
+  SummaryEntry,
+  SummaryLevel,
+  PhaseType,
+} from '../types/index.js';
+import { AutobiographicalStrategy, type Chunk } from './autobiographical.js';
+
+const DEFAULT_RESEARCH_PREFIXES = ['mcpl:', 'zulip:'];
+const DEFAULT_SUBAGENT_PREFIXES = ['subagent:'];
+const DEFAULT_LESSON_NAMES = ['lessons:create', 'lessons:update'];
+
+/**
+ * Domain-aware compression strategy for knowledge extraction workflows.
+ *
+ * Builds on AutobiographicalStrategy's hierarchical pyramid (L1/L2/L3)
+ * but changes three things:
+ * 1. Semantic chunking — chunks at phase transitions instead of fixed token counts
+ * 2. Phase-aware compression — different prompts per phase type
+ * 3. Asymmetric budget — caps research, prioritizes synthesis in L1 selection
+ *
+ * Also adds [LEAD] tracking: unresolved questions/leads are flagged in summaries
+ * and preserved across compression levels.
+ */
+export class KnowledgeStrategy extends AutobiographicalStrategy {
+  readonly name = 'knowledge' as const;
+
+  private knowledgeConfig: KnowledgeConfig;
+
+  constructor(config: Partial<KnowledgeConfig> = {}) {
+    // Force hierarchical mode
+    super({ ...config, hierarchical: true });
+    // Merge knowledge-specific fields onto the base config so all KnowledgeConfig
+    // fields are actually present (super() only stores AutobiographicalConfig fields).
+    this.knowledgeConfig = { ...this.config, ...config } as KnowledgeConfig;
+  }
+
+  // ============================================================================
+  // Override: Semantic chunking
+  // ============================================================================
+
+  protected rebuildChunks(store: MessageStoreView): void {
+    const messagesToChunk = this.getCompressibleMessages(store);
+
+    // Preserve existing compressed chunks
+    const existingCompressed = new Map<string, Chunk>();
+    for (const chunk of this.chunks) {
+      if (chunk.compressed) {
+        existingCompressed.set(this.chunkKey(chunk), chunk);
+      }
+    }
+
+    this.chunks = [];
+    this.compressionQueue = [];
+
+    let currentChunk: StoredMessage[] = [];
+    let currentTokens = 0;
+    let currentPhase: PhaseType | null = null;
+    let lastToolPhase: PhaseType = 'synthesis';
+    let chunkFilteredStart = 0;
+
+    for (let i = 0; i < messagesToChunk.length; i++) {
+      const msg = messagesToChunk[i];
+      const phase = this.classifyMessage(msg, lastToolPhase);
+
+      // Track tool phase for tool_result inheritance
+      if (this.getToolNames(msg).length > 0) {
+        lastToolPhase = phase;
+      }
+
+      let msgTokens = store.estimateTokens(msg);
+      if (this.config.attachmentsIgnoreSize) {
+        msgTokens = this.estimateTextOnlyTokens(msg);
+      }
+
+      // Semantic chunking uses a minimum of 2 messages (vs parent's 4) because
+      // phase transitions are the primary chunk boundary signal. A tool_use + tool_result
+      // pair is already a meaningful unit of work worth compressing independently.
+      const phaseChanged = currentPhase !== null && phase !== currentPhase;
+      const maxTokens = this.getMaxChunkTokens(currentPhase ?? phase);
+      const sizeExceeded = currentTokens >= maxTokens;
+      const shouldClose = currentChunk.length >= 2 && (phaseChanged || sizeExceeded);
+
+      if (shouldClose) {
+        const chunk = this.createChunk(
+          this.chunks.length,
+          chunkFilteredStart,
+          i,
+          currentChunk,
+          currentTokens,
+          existingCompressed
+        );
+        chunk.phaseType = currentPhase!;
+        this.chunks.push(chunk);
+        if (!chunk.compressed) this.compressionQueue.push(chunk.index);
+
+        currentChunk = [];
+        currentTokens = 0;
+        chunkFilteredStart = i;
+      }
+
+      currentChunk.push(msg);
+      currentTokens += msgTokens;
+      currentPhase = phase;
+    }
+
+    // Final remaining chunk (minimum 1 message to avoid silent drops)
+    if (currentChunk.length >= 1 && currentPhase) {
+      const chunk = this.createChunk(
+        this.chunks.length,
+        chunkFilteredStart,
+        messagesToChunk.length,
+        currentChunk,
+        currentTokens,
+        existingCompressed
+      );
+      chunk.phaseType = currentPhase;
+      this.chunks.push(chunk);
+      if (!chunk.compressed) this.compressionQueue.push(chunk.index);
+    }
+  }
+
+  // ============================================================================
+  // Override: Phase-aware compression prompts
+  // ============================================================================
+
+  protected getCompressionInstruction(chunk: Chunk, targetTokens: number): string {
+    const leadSuffix = 'If any leads or open questions were identified but not yet pursued, mark them with [LEAD].';
+
+    switch (chunk.phaseType) {
+      case 'research':
+        return (
+          `Summarize the research performed. What was searched for, what sources were consulted, ` +
+          `and what was found? Note any leads discovered. Be terse — the raw data is not needed, ` +
+          `only what was learned. ${leadSuffix} Aim for about ${targetTokens} tokens.`
+        );
+
+      case 'synthesis':
+        return (
+          `Capture the reasoning and conclusions from this discussion. What connections were drawn? ` +
+          `What hypotheses were formed or rejected? What decisions were made about what to ` +
+          `investigate next? Preserve the logic chain. ${leadSuffix} Aim for about ${targetTokens} tokens.`
+        );
+
+      case 'lesson':
+        return (
+          `Record what knowledge was captured. What lessons were created or updated? ` +
+          `What was the evidence basis? Note any confidence gaps or unresolved questions. ` +
+          `${leadSuffix} Aim for about ${targetTokens} tokens.`
+        );
+
+      case 'subagent':
+        return (
+          `Summarize the subagent work. What tasks were dispatched, what did each return, ` +
+          `and what was the coordinator's synthesis of the results? Collapse dispatch/wait mechanics. ` +
+          `${leadSuffix} Aim for about ${targetTokens} tokens.`
+        );
+
+      default:
+        return super.getCompressionInstruction(chunk, targetTokens);
+    }
+  }
+
+  protected getMergeInstruction(
+    targetLevel: SummaryLevel,
+    sources: SummaryEntry[],
+    targetTokens: number
+  ): string {
+    // Describe the phase composition of the sources
+    const phaseCounts = new Map<string, number>();
+    for (const s of sources) {
+      const phase = s.phaseType ?? 'unknown';
+      phaseCounts.set(phase, (phaseCounts.get(phase) ?? 0) + 1);
+    }
+    const phaseDesc = [...phaseCounts.entries()]
+      .map(([phase, count]) => `${count} ${phase}`)
+      .join(', ');
+
+    const levelLabel = targetLevel === 2 ? 'L1 summaries' : 'L2 summaries';
+
+    return (
+      `Please consolidate these ${sources.length} ${levelLabel} (${phaseDesc}) ` +
+      `into a single cohesive memory. ` +
+      `Aim for about ${targetTokens} tokens. Write as you would to yourself — this is your ` +
+      `autobiography, capturing the arc of what happened. ` +
+      `IMPORTANT: Preserve any items marked with [LEAD] — these are unresolved questions ` +
+      `that must survive consolidation until explicitly resolved or dropped.`
+    );
+  }
+
+  // ============================================================================
+  // Override: Asymmetric L1 budget allocation
+  // ============================================================================
+
+  protected selectL1Summaries(
+    shownL1: SummaryEntry[],
+    budget: number,
+    maxTokens: number
+  ): { selected: SummaryEntry[]; tokensUsed: number } {
+    const effectiveBudget = Math.min(budget, maxTokens);
+
+    const researchCap = effectiveBudget * (this.knowledgeConfig.researchL1BudgetCap ?? 0.3);
+    const synthesisFloor = effectiveBudget * (this.knowledgeConfig.synthesisL1BudgetFloor ?? 0.4);
+
+    // Partition by phase
+    const synthesis: SummaryEntry[] = [];
+    const lessons: SummaryEntry[] = [];
+    const subagent: SummaryEntry[] = [];
+    const research: SummaryEntry[] = [];
+    const other: SummaryEntry[] = [];
+
+    for (const s of shownL1) {
+      switch (s.phaseType) {
+        case 'synthesis': synthesis.push(s); break;
+        case 'lesson': lessons.push(s); break;
+        case 'subagent': subagent.push(s); break;
+        case 'research': research.push(s); break;
+        default: other.push(s); break;
+      }
+    }
+
+    const selected: SummaryEntry[] = [];
+    let used = 0;
+
+    // Priority 1: Synthesis — guaranteed floor, can go higher if budget allows
+    for (const s of synthesis) {
+      if (used + s.tokens > effectiveBudget) break;
+      // Keep going past the floor, but cap synthesis to avoid starving other phases
+      const synthesisCap = effectiveBudget * (this.knowledgeConfig.synthesisL1BudgetCap ?? 0.7);
+      if (used >= synthesisFloor && used + s.tokens > synthesisCap) break;
+      selected.push(s);
+      used += s.tokens;
+    }
+
+    // Priority 2: Lessons — high value, no cap
+    for (const s of lessons) {
+      if (used + s.tokens > effectiveBudget) break;
+      selected.push(s);
+      used += s.tokens;
+    }
+
+    // Priority 3: Subagent — moderate value, no cap
+    for (const s of [...subagent, ...other]) {
+      if (used + s.tokens > effectiveBudget) break;
+      selected.push(s);
+      used += s.tokens;
+    }
+
+    // Priority 4: Research — capped
+    let researchUsed = 0;
+    for (const s of research) {
+      if (researchUsed + s.tokens > researchCap) break;
+      if (used + s.tokens > effectiveBudget) break;
+      selected.push(s);
+      researchUsed += s.tokens;
+      used += s.tokens;
+    }
+
+    return { selected, tokensUsed: used };
+  }
+
+  // ============================================================================
+  // Phase detection
+  // ============================================================================
+
+  /**
+   * Classify a single message by the phase it belongs to.
+   * Uses tool_use block names for classification.
+   * Messages with only tool_result (no tool_use) inherit from the last tool phase.
+   */
+  private classifyMessage(msg: StoredMessage, lastToolPhase: PhaseType): PhaseType {
+    const toolNames = this.getToolNames(msg);
+
+    if (toolNames.length > 0) {
+      return this.classifyByToolNames(toolNames);
+    }
+
+    // tool_result without tool_use → inherit from preceding tool phase
+    if (this.hasToolResult(msg)) {
+      return lastToolPhase;
+    }
+
+    // Pure dialogue
+    return 'synthesis';
+  }
+
+  /**
+   * Classify by tool names with priority: lesson > subagent > research > synthesis.
+   */
+  private classifyByToolNames(toolNames: string[]): PhaseType {
+    const lessonNames = this.knowledgeConfig.lessonToolNames ?? DEFAULT_LESSON_NAMES;
+    const subagentPrefixes = this.knowledgeConfig.subagentToolPrefixes ?? DEFAULT_SUBAGENT_PREFIXES;
+    const researchPrefixes = this.knowledgeConfig.researchToolPrefixes ?? DEFAULT_RESEARCH_PREFIXES;
+
+    if (toolNames.some(n => lessonNames.includes(n))) return 'lesson';
+    if (toolNames.some(n => subagentPrefixes.some(p => n.startsWith(p)))) return 'subagent';
+    if (toolNames.some(n => researchPrefixes.some(p => n.startsWith(p)))) return 'research';
+
+    return 'synthesis';
+  }
+
+  /**
+   * Extract tool names from tool_use blocks in a message.
+   */
+  private getToolNames(msg: StoredMessage): string[] {
+    const names: string[] = [];
+    for (const block of msg.content) {
+      if (block.type === 'tool_use') {
+        names.push((block as { type: 'tool_use'; name: string }).name);
+      }
+    }
+    return names;
+  }
+
+  /**
+   * Get the maximum chunk token size for a given phase.
+   * Research and subagent chunks can grow larger since they compress aggressively.
+   */
+  private getMaxChunkTokens(phase: PhaseType): number {
+    const base = this.config.targetChunkTokens;
+    switch (phase) {
+      case 'research':
+        return this.knowledgeConfig.maxResearchChunkTokens ?? base * 2;
+      case 'subagent':
+        return this.knowledgeConfig.maxSubagentChunkTokens ?? base * 2;
+      case 'synthesis':
+        return this.knowledgeConfig.maxSynthesisChunkTokens ?? Math.round(base * 1.5);
+      case 'lesson':
+        return this.knowledgeConfig.maxLessonChunkTokens ?? base;
+      default:
+        return base;
+    }
+  }
+}

package/src/strategies/passthrough.ts

@@ -0,0 +1,98 @@
+import type {
+  ContextStrategy,
+  StrategyContext,
+  ReadinessState,
+  MessageStoreView,
+  ContextLogView,
+  TokenBudget,
+  ContextEntry,
+  StoredMessage,
+} from '../types/index.js';
+
+/**
+ * Simple passthrough strategy that copies all messages to context.
+ * No compression, no background work. Always ready.
+ * Good for testing and simple use cases.
+ */
+export class PassthroughStrategy implements ContextStrategy {
+  readonly name = 'passthrough';
+
+  checkReadiness(): ReadinessState {
+    return { ready: true };
+  }
+
+  async onNewMessage(message: StoredMessage, ctx: StrategyContext): Promise<void> {
+    // No-op: context is rebuilt on select()
+  }
+
+  select(
+    store: MessageStoreView,
+    _log: ContextLogView,
+    budget: TokenBudget
+  ): ContextEntry[] {
+    const messages = store.getAll();
+    const entries: ContextEntry[] = [];
+    let totalTokens = 0;
+    const maxTokens = budget.maxTokens - budget.reserveForResponse;
+
+    // Add messages until we hit the budget
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      const tokens = store.estimateTokens(msg);
+
+      if (totalTokens + tokens > maxTokens) {
+        // If we're over budget, start from the end and work backwards
+        break;
+      }
+
+      entries.push({
+        index: i,
+        sourceMessageId: msg.id,
+        sourceRelation: 'copy',
+        participant: msg.participant,
+        content: msg.content,
+      });
+
+      totalTokens += tokens;
+    }
+
+    // If we hit the limit before adding all messages,
+    // keep the most recent ones that fit
+    if (entries.length < messages.length) {
+      return this.selectFromEnd(store, maxTokens);
+    }
+
+    return entries;
+  }
+
+  /**
+   * Select messages from the end when we can't fit everything.
+   */
+  private selectFromEnd(store: MessageStoreView, maxTokens: number): ContextEntry[] {
+    const messages = store.getAll();
+    const entries: ContextEntry[] = [];
+    let totalTokens = 0;
+
+    // Work backwards from the most recent
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      const tokens = store.estimateTokens(msg);
+
+      if (totalTokens + tokens > maxTokens) {
+        break;
+      }
+
+      entries.unshift({
+        index: i,
+        sourceMessageId: msg.id,
+        sourceRelation: 'copy',
+        participant: msg.participant,
+        content: msg.content,
+      });
+
+      totalTokens += tokens;
+    }
+
+    return entries;
+  }
+}

package/src/types/context.ts

@@ -0,0 +1,119 @@
+import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
+import type { MessageId, StoredContentBlock } from './message.js';
+
+/**
+ * Describes how a context entry relates to its source message.
+ * This determines edit propagation behavior.
+ */
+export type SourceRelation =
+  /** Direct copy - edits MUST propagate */
+  | 'copy'
+  /** Summary/compression - edits MAY be ignored (stale is acceptable) */
+  | 'derived'
+  /** Just mentions source - edits DON'T propagate */
+  | 'referenced';
+
+/**
+ * An entry in the context log.
+ * The context log is a materialized, editable working set derived from the message store.
+ */
+export interface ContextEntry {
+  /** Index in the context log */
+  index: number;
+  /** Source message ID (if derived from message store) */
+  sourceMessageId?: MessageId;
+  /** How this entry relates to its source */
+  sourceRelation?: SourceRelation;
+  /** Participant name */
+  participant: string;
+  /** Materialized content blocks */
+  content: ContentBlock[];
+  /** For prompt caching (future) */
+  cacheMarker?: boolean;
+}
+
+/**
+ * Internal representation with blob references for storage.
+ */
+export interface ContextEntryInternal {
+  index: number;
+  sourceMessageId?: MessageId;
+  sourceRelation?: SourceRelation;
+  participant: string;
+  content: StoredContentBlock[];
+  cacheMarker?: boolean;
+}
+
+/**
+ * Token budget for context compilation.
+ */
+export interface TokenBudget {
+  /** Maximum tokens for the context window */
+  maxTokens: number;
+  /** Reserve this many tokens for model response */
+  reserveForResponse: number;
+}
+
+/**
+ * Information about pending background work.
+ */
+export interface PendingWork {
+  /** Human-readable description */
+  description: string;
+  /** Estimated time to completion in ms */
+  estimatedMs?: number;
+  /** When the work started */
+  started: Date;
+}
+
+/**
+ * An injection into the compiled context.
+ * Source-agnostic: may come from MCPL servers, local strategies, or application code.
+ */
+export interface ContextInjection {
+  /** Server-defined namespace (e.g., "memory", "compliance") */
+  namespace: string;
+
+  /** Where to inject in the message array */
+  position: 'system' | 'beforeUser' | 'afterUser';
+
+  /** Content blocks to inject (multimodal) */
+  content: ContentBlock[];
+
+  /** Arbitrary metadata (passed through, not interpreted) */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of context compilation.
+ * Separates system-position injections from message-level content.
+ */
+export interface CompileResult {
+  /** Compiled messages (includes beforeUser/afterUser injections merged in) */
+  messages: NormalizedMessage[];
+
+  /**
+   * System-position injections, grouped by namespace.
+   * Caller should append these to the system prompt.
+   * Separated because the system prompt is outside context-manager's scope.
+   */
+  systemInjections: ContentBlock[];
+}
+
+/**
+ * Branch information.
+ */
+export interface BranchInfo {
+  /** Branch identifier */
+  id: string;
+  /** Branch name */
+  name: string;
+  /** Current head sequence */
+  head: number;
+  /** Parent branch ID */
+  parentId?: string;
+  /** Sequence at which branch was created */
+  branchPoint?: number;
+  /** Creation timestamp */
+  created: Date;
+}

package/src/types/index.ts

@@ -0,0 +1,42 @@
+// Message types
+export type {
+  MessageId,
+  Sequence,
+  BranchId,
+  MessageMetadata,
+  StoredMessage,
+  BlobReference,
+  StoredContentBlock,
+  StoredMessageInternal,
+  MessageQuery,
+  MessageQueryResult,
+} from './message.js';
+
+// Context types
+export type {
+  SourceRelation,
+  ContextEntry,
+  ContextEntryInternal,
+  TokenBudget,
+  PendingWork,
+  BranchInfo,
+  ContextInjection,
+  CompileResult,
+} from './context.js';
+
+// Strategy types
+export type {
+  MessageStoreView,
+  ContextLogView,
+  StrategyContext,
+  ReadinessState,
+  ContextStrategy,
+  AutobiographicalConfig,
+  SummaryLevel,
+  SummaryEntry,
+  PhaseType,
+  KnowledgeConfig,
+  ResettableStrategy,
+} from './strategy.js';
+
+export { DEFAULT_AUTOBIOGRAPHICAL_CONFIG, isResettableStrategy } from './strategy.js';