@andre.li/memoark 0.3.1 → 0.3.2

package/dist/extractors/playbook-extractor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Playbook-aware extractor (Spec 11 §五).
+ *
+ * Two-part flow attached to the SignalExtractor stage of the pipeline:
+ *
+ *   1. pre-classify (`classifyPlaybook`): a lightweight rule-based check — does this
+ *      block describe a troubleshooting *procedure*? Cheap keyword heuristics; an
+ *      optional LLM second-check refines borderline cases.
+ *   2. playbook extraction (`extractPlaybookDraft`): on a hit, ask the LLM to emit the
+ *      §四 markdown structure (适用场景 / 步骤 / 命中→含义分支 / 关联 `[[rel:slug]]`) and
+ *      write a `type=playbook` *draft* page (`frontmatter.confidence = "inferred"`,
+ *      tag `draft`). The page body IS the compiled_truth (text/markdown, not JSON).
+ *
+ * Draft pages await human confirmation (→ `confidence: confirmed`). Wikilinks in the
+ * body auto-wire hierarchy/order edges via Spec 10 on putPage.
+ */
+import type { ConversationBlock } from "../core/types.js";
+import type { LLMProvider } from "./providers/types.js";
+/**
+ * Rule-based pre-classify: is `text` a troubleshooting procedure? Zero-LLM, cheap.
+ * Requires at least two distinct signals (keyword hits and/or a conditional branch)
+ * so ordinary chatter that merely mentions one keyword is not misclassified.
+ */
+export declare function classifyPlaybook(text: string): boolean;
+/** Minimal store surface the playbook extractor needs (a PageStore-compatible `putPage`). */
+export interface PlaybookPageWriter {
+    putPage(slug: string, content: string): Promise<unknown>;
+}
+/**
+ * Run the playbook extraction branch: LLM produces §四 markdown, write a draft
+ * `type=playbook` page. Returns the written slug, or null when the LLM produced no
+ * usable body. Never throws on empty output.
+ */
+export declare function extractPlaybookDraft(block: ConversationBlock, provider: LLMProvider, pages: PlaybookPageWriter): Promise<string | null>;
+//# sourceMappingURL=playbook-extractor.d.ts.map

package/dist/extractors/playbook-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/playbook-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOxD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQtD;AAwCD,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BxB"}

package/dist/extractors/playbook-extractor.js

@@ -0,0 +1,98 @@
+/**
+ * Playbook-aware extractor (Spec 11 §五).
+ *
+ * Two-part flow attached to the SignalExtractor stage of the pipeline:
+ *
+ *   1. pre-classify (`classifyPlaybook`): a lightweight rule-based check — does this
+ *      block describe a troubleshooting *procedure*? Cheap keyword heuristics; an
+ *      optional LLM second-check refines borderline cases.
+ *   2. playbook extraction (`extractPlaybookDraft`): on a hit, ask the LLM to emit the
+ *      §四 markdown structure (适用场景 / 步骤 / 命中→含义分支 / 关联 `[[rel:slug]]`) and
+ *      write a `type=playbook` *draft* page (`frontmatter.confidence = "inferred"`,
+ *      tag `draft`). The page body IS the compiled_truth (text/markdown, not JSON).
+ *
+ * Draft pages await human confirmation (→ `confidence: confirmed`). Wikilinks in the
+ * body auto-wire hierarchy/order edges via Spec 10 on putPage.
+ */
+import { createHash } from "node:crypto";
+// Rule keywords that signal a troubleshooting / runbook flow (Spec 11 §五 A).
+const PLAYBOOK_KEYWORDS = ["排查", "步骤", "grep", "日志", "runbook", "playbook"];
+// "如果……则" conditional-branch pattern.
+const CONDITIONAL_RE = /如果[\s\S]{0,40}?则/;
+/**
+ * Rule-based pre-classify: is `text` a troubleshooting procedure? Zero-LLM, cheap.
+ * Requires at least two distinct signals (keyword hits and/or a conditional branch)
+ * so ordinary chatter that merely mentions one keyword is not misclassified.
+ */
+export function classifyPlaybook(text) {
+    const lower = text.toLowerCase();
+    let hits = 0;
+    for (const kw of PLAYBOOK_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            hits++;
+    }
+    if (CONDITIONAL_RE.test(text))
+        hits++;
+    return hits >= 2;
+}
+const PLAYBOOK_EXTRACT_PROMPT = [
+    "你是排查手册（playbook）抽取器。下面是一段排查类对话/文档。",
+    "请把它整理为 markdown 排查手册，严格使用以下结构：",
+    "## 适用场景\n（一句话描述何时用）",
+    "## 步骤\n（有序步骤；命中某结果时用 `- 命中 X → 含义/下一步` 表达分支）",
+    "## 关联\n（用 [[part_of:problem-class/...]] / [[precedes:playbook/...]] 标注层级与顺序，可省略）",
+    "只输出 markdown 正文，不要额外解释，不要代码围栏，不要 frontmatter。",
+].join("\n\n");
+function formatConversation(messages) {
+    return messages
+        .map((m) => `[${new Date(m.timestamp).toISOString()}] ${m.contact}: ${m.content}`)
+        .join("\n");
+}
+function kebabCase(str) {
+    const ascii = str
+        .toLowerCase()
+        .replace(/[^a-z0-9一-鿿]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (ascii.length >= 3)
+        return ascii;
+    const hash = createHash("sha256").update(str).digest("hex").slice(0, 12);
+    return ascii ? `${ascii}-${hash}` : hash;
+}
+/** Derive a playbook title from the first non-empty line / first messages of the block. */
+function deriveTitle(block) {
+    const firstContent = block.messages[0]?.content ?? "";
+    const firstLine = firstContent.split("\n").find((l) => l.trim().length > 0) ?? "playbook";
+    // Trim to a reasonable title length; strip trailing punctuation.
+    return (firstLine
+        .trim()
+        .replace(/[：:。.\s]+$/, "")
+        .slice(0, 40) || "playbook");
+}
+/**
+ * Run the playbook extraction branch: LLM produces §四 markdown, write a draft
+ * `type=playbook` page. Returns the written slug, or null when the LLM produced no
+ * usable body. Never throws on empty output.
+ */
+export async function extractPlaybookDraft(block, provider, pages) {
+    const conversation = formatConversation(block.messages);
+    const body = (await provider.chat([
+        { role: "system", content: PLAYBOOK_EXTRACT_PROMPT },
+        { role: "user", content: conversation },
+    ], { responseFormat: "text", temperature: 0.2 })).trim();
+    if (!body)
+        return null;
+    const title = deriveTitle(block);
+    const slug = `playbook/${kebabCase(title)}`;
+    const frontmatter = [
+        "---",
+        `title: ${title}`,
+        "type: playbook",
+        "confidence: inferred",
+        "tags:",
+        "  - draft",
+        "---",
+    ].join("\n");
+    await pages.putPage(slug, `${frontmatter}\n${body}`);
+    return slug;
+}
+//# sourceMappingURL=playbook-extractor.js.map

package/dist/extractors/playbook-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-extractor.js","sourceRoot":"","sources":["../../src/extractors/playbook-extractor.ts"],"names":[],"mappings":"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"}

package/dist/extractors/prompts/examples/agent-session.md

@@ -0,0 +1,257 @@
+# Example: Agent Session Extraction
+
+## Input Conversation
+
+```
+[2024-01-15T10:00:00Z] → Alice: We need to migrate from sessions to JWT for the auth system
+[2024-01-15T10:01:30Z] ← Bob: Makes sense for scaling. I can start this week.
+[2024-01-15T10:02:15Z] → Alice: Perfect. Let's use the HS256 algorithm initially.
+[2024-01-15T10:03:00Z] ← Bob: Got it. Should we add refresh tokens too?
+[2024-01-15T10:03:45Z] → Alice: Yes, 7-day access tokens and 30-day refresh tokens.
+[2024-01-15T10:04:30Z] ← Bob: I'll document the decision in the wiki before implementing.
+```
+
+## Output JSON
+
+```json
+{
+  "source": {
+    "platform": "slack",
+    "channel": "#engineering",
+    "timestamp": "2024-01-15T10:00:00Z",
+    "thread_id": "thread-auth-migration",
+    "raw_hash": "abc123def456",
+    "quote": "We need to migrate from sessions to JWT for the auth system"
+  },
+  "entities": [
+    {
+      "slug": "person/alice",
+      "name": "Alice",
+      "type": "person",
+      "context": "Engineering lead discussing auth migration",
+      "confidence": "direct"
+    },
+    {
+      "slug": "person/bob",
+      "name": "Bob",
+      "type": "person",
+      "context": "Developer implementing JWT auth system",
+      "confidence": "direct"
+    },
+    {
+      "slug": "project/auth-system",
+      "name": "Auth System",
+      "type": "project",
+      "context": "Authentication system being migrated to JWT",
+      "confidence": "direct"
+    },
+    {
+      "slug": "tool/jwt",
+      "name": "JWT (JSON Web Tokens)",
+      "type": "tool",
+      "context": "Token-based authentication mechanism replacing sessions",
+      "confidence": "direct"
+    },
+    {
+      "slug": "concept/refresh-tokens",
+      "name": "Refresh Tokens",
+      "type": "concept",
+      "context": "30-day tokens for obtaining new access tokens",
+      "confidence": "direct"
+    }
+  ],
+  "timeline": [
+    {
+      "date": "2024-01-15",
+      "summary": "Decision to migrate from sessions to JWT authentication",
+      "entities": ["person/alice", "person/bob", "project/auth-system", "tool/jwt"],
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:00:00Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "We need to migrate from sessions to JWT for the auth system"
+      },
+      "confidence": "direct"
+    },
+    {
+      "date": "2024-01-15",
+      "summary": "Bob commits to starting JWT migration this week",
+      "entities": ["person/bob", "project/auth-system"],
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:01:30Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "Makes sense for scaling. I can start this week."
+      },
+      "confidence": "direct"
+    }
+  ],
+  "links": [
+    {
+      "from": "person/bob",
+      "to": "project/auth-system",
+      "type": "works_on",
+      "context": "Bob is implementing the JWT migration for auth system",
+      "confidence": "direct"
+    },
+    {
+      "from": "project/auth-system",
+      "to": "tool/jwt",
+      "type": "depends_on",
+      "context": "Auth system will use JWT for token-based authentication",
+      "confidence": "direct"
+    },
+    {
+      "from": "person/alice",
+      "to": "project/auth-system",
+      "type": "works_on",
+      "context": "Alice is leading the auth system migration decision",
+      "confidence": "paraphrased"
+    }
+  ],
+  "decisions": [
+    {
+      "summary": "Migrate authentication from sessions to JWT",
+      "reasoning": "Better for scaling across multiple instances",
+      "alternatives": ["Keep session-based auth", "Use OAuth2"],
+      "entities": ["project/auth-system", "tool/jwt"],
+      "date": "2024-01-15",
+      "confidence": "direct",
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:00:00Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "We need to migrate from sessions to JWT for the auth system"
+      }
+    },
+    {
+      "summary": "Use HS256 algorithm for JWT signing",
+      "entities": ["tool/jwt"],
+      "date": "2024-01-15",
+      "confidence": "direct",
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:02:15Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "Let's use the HS256 algorithm initially."
+      }
+    },
+    {
+      "summary": "Token expiration: 7-day access tokens, 30-day refresh tokens",
+      "entities": ["tool/jwt", "concept/refresh-tokens"],
+      "date": "2024-01-15",
+      "confidence": "direct",
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:03:45Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "Yes, 7-day access tokens and 30-day refresh tokens."
+      }
+    }
+  ],
+  "tasks": [
+    {
+      "title": "Implement JWT-based authentication",
+      "status": "open",
+      "owner": "person/bob",
+      "project": "project/auth-system",
+      "valid_at": "2024-01-15T10:01:30Z",
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:01:30Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "I can start this week."
+      },
+      "confidence": "direct"
+    },
+    {
+      "title": "Document JWT migration decision in wiki",
+      "status": "open",
+      "owner": "person/bob",
+      "project": "project/auth-system",
+      "valid_at": "2024-01-15T10:04:30Z",
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:04:30Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "I'll document the decision in the wiki before implementing."
+      },
+      "confidence": "direct"
+    }
+  ],
+  "discoveries": [
+    {
+      "summary": "Session-based auth doesn't scale well across multiple instances",
+      "type": "insight",
+      "entities": ["project/auth-system"],
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:01:30Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "Makes sense for scaling."
+      },
+      "confidence": "paraphrased"
+    },
+    {
+      "summary": "Document architectural decisions before implementation",
+      "type": "procedure",
+      "entities": ["person/bob"],
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:04:30Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "I'll document the decision in the wiki before implementing."
+      },
+      "confidence": "direct"
+    }
+  ],
+  "knowledge": [
+    {
+      "topic": "jwt-token-expiration",
+      "content": "Access tokens should be short-lived (minutes to hours) while refresh tokens can be longer-lived (days to weeks) to balance security with user experience",
+      "source_type": "teaching",
+      "related_entities": ["tool/jwt", "concept/refresh-tokens"],
+      "source": {
+        "platform": "slack",
+        "channel": "#engineering",
+        "timestamp": "2024-01-15T10:03:45Z",
+        "thread_id": "thread-auth-migration",
+        "raw_hash": "abc123def456",
+        "quote": "Yes, 7-day access tokens and 30-day refresh tokens."
+      },
+      "confidence": "paraphrased"
+    }
+  ]
+}
+```
+
+## Key Takeaways from This Example
+
+1. **Entity consistency**: Same person/project mentioned multiple times uses the same slug
+2. **Confidence levels**: Most are "direct" (explicit), some "paraphrased" (clear implication)
+3. **Rich context**: Each signal includes enough context to understand it standalone
+4. **Quotes**: All under 300 chars, capturing the key statement
+5. **Links**: Connect entities with specific relationship types
+6. **Timeline**: Events ordered chronologically with clear summaries
+7. **Decisions**: Capture not just what was decided, but why and what alternatives existed
+8. **Tasks**: Include owner, status, and timing information
+9. **Discoveries**: Extract both insights (learnings) and procedures (how-to)
+10. **Knowledge**: Extract reusable facts that stand alone without the original conversation context

package/dist/extractors/prompts/signal-extract.md

@@ -0,0 +1,199 @@
+# Signal Extraction Task
+
+Extract structured signals from the provided conversation block following the schema below.
+
+## Output Schema
+
+```typescript
+interface ExtractionResult {
+  source: SourceRef;
+  entities: Entity[];
+  timeline: TimelineEntry[];
+  links: Link[];
+  decisions: Decision[];
+  tasks: TaskSignal[];
+  discoveries: Discovery[];
+  knowledge: Knowledge[];
+}
+
+interface SourceRef {
+  platform: string;          // e.g., "slack", "claude-code"
+  channel: string;           // e.g., "#general", "session-123"
+  timestamp: string;         // ISO 8601
+  message_id?: string;
+  thread_id?: string;
+  file_path?: string;
+  line_range?: { start: number; end: number };
+  attachment_id?: string;
+  url?: string;
+  raw_hash: string;          // generated by system
+  quote: string;             // ≤ 300 chars, most relevant excerpt
+}
+
+interface Entity {
+  slug: string;              // Format: {type}/{kebab-name}
+  name: string;              // Display name
+  type: 'person' | 'project' | 'organization' | 'tool' | 'concept';
+  context: string;           // Brief description
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+}
+
+interface TimelineEntry {
+  date: string;              // ISO 8601 or partial (YYYY-MM, YYYY)
+  summary: string;           // Event description
+  entities: string[];        // Slugs of involved entities
+  source: SourceRef;
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+}
+
+interface Link {
+  from: string;              // Entity slug
+  to: string;                // Entity slug
+  type: 'works_on' | 'works_at' | 'reports_to' | 'collaborates' | 'depends_on' | 'mentions' | 'custom';
+  context: string;           // Description of relationship
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+  source: SourceRef;
+}
+
+interface Decision {
+  summary: string;           // What was decided
+  reasoning?: string;        // Why (if mentioned)
+  alternatives?: string[];   // Other options considered
+  entities: string[];        // Slugs of entities involved
+  date: string;              // ISO 8601
+  valid_at?: string;         // When decision takes effect
+  invalid_at?: string;       // When decision expires/superseded
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+  source: SourceRef;
+}
+
+interface TaskSignal {
+  title: string;             // Task description
+  status: 'open' | 'in_progress' | 'done' | 'cancelled';
+  owner?: string;            // Entity slug
+  project?: string;          // Entity slug
+  due_date?: string;         // ISO 8601
+  valid_at?: string;         // When task was created
+  invalid_at?: string;       // When task was closed
+  source: SourceRef;
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+}
+
+interface Discovery {
+  summary: string;           // Brief insight
+  detail?: string;           // Extended explanation
+  type: 'procedure' | 'preference' | 'pattern' | 'insight';
+  entities: string[];        // Slugs of related entities
+  source: SourceRef;
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+}
+interface Knowledge {
+  topic: string;              // kebab-case topic tag: "react-hooks", "feishu-api"
+  content: string;            // Decontextualized knowledge statement
+  source_type: 'conversation' | 'document' | 'teaching';
+  related_entities: string[]; // Entity slugs (may reference entities not in this block)
+  valid_at?: string;          // ISO 8601, when knowledge becomes valid
+  invalid_at?: string;        // ISO 8601, when knowledge expires
+  source: SourceRef;
+  confidence: 'direct' | 'paraphrased' | 'inferred' | 'speculative';
+}
+```
+
+## Extraction Rules
+
+### Entity Slugs
+- Format: `{type}/{kebab-case-name}`
+- Examples: `person/alice-smith`, `project/auth-system`, `tool/github-actions`
+- Be consistent: same entity = same slug across all signals
+- For people: use recognizable name (first name + last initial if ambiguous)
+- For projects/tools: use official name or widely-used abbreviation
+
+### Quotes
+- Maximum 300 characters
+- Select the most informative excerpt
+- Don't fabricate - copy exact text (can trim with "...")
+- Should stand alone and convey key context
+
+### Confidence Levels
+- **direct**: Explicitly stated ("Alice will lead the auth project")
+- **paraphrased**: Clear implication with different wording ("Alice is taking charge of authentication")
+- **inferred**: Reasonable deduction ("Alice keeps talking about auth, likely leading it")
+- **speculative**: Uncertain but possible ("Alice might be involved based on previous mentions")
+
+### Dates
+- Prefer ISO 8601: `2024-01-15T10:30:00Z`
+- Partial dates OK: `2024-01` (month), `2024` (year)
+- Relative dates: resolve to absolute if possible ("last Tuesday" → `2024-01-09`)
+- Uncertain dates: use best estimate with lower confidence
+
+### Empty Results
+- If no signals found, return empty arrays for all categories
+- Still include valid `source` with platform, channel, timestamp, and quote
+
+### Knowledge vs Discovery
+
+Knowledge (知识): Decontextualized, reusable facts or concepts
+  ✓ "React useEffect runs twice in StrictMode during development"
+  ✓ "Feishu API global rate limit is 50 QPS"
+  ✓ "TCP three-way handshake prevents stale connection requests"
+
+Discovery (发现): Scene-bound, time-bound findings
+  ✓ "Today's integration test found 5s latency on this endpoint"
+  ✓ "Root cause of this bug is a race condition"
+  ✓ "Local Docker DNS resolution is broken"
+
+Rules:
+  1. Remove time/scene info — is the statement still valid and valuable? Yes → Knowledge
+  2. Could this be a FAQ or documentation entry as-is? Yes → Knowledge
+  3. If uncertain, prefer Discovery (conservative)
+
+### Knowledge vs Decision
+
+Knowledge: Norms, facts, concepts — objective, verifiable
+  ✓ "Feishu API global rate limit is 50 QPS"
+  ✓ "Go goroutine initial stack size is 2KB"
+
+Decision: Team/project choices, commitments — subjective, has an owner
+  ✓ "All services will use OpenTelemetry going forward"
+  ✓ "We decided to replace MySQL with PostgreSQL"
+
+Rules:
+  1. Has an explicit decision-maker or team commitment? → Decision
+  2. Would this statement hold true for a different team/project? → Knowledge
+  3. If uncertain, look for verbs like "decided", "chose", "switched to" → Decision
+
+### Knowledge source_type
+
+- `conversation`: Extracted from group/private chat messages
+- `document`: Extracted from cloud document content
+- `teaching`: Someone actively explaining/teaching (systematic explanation of principles, steps, processes)
+
+### Knowledge topic
+
+- Output kebab-case ASCII when possible: "react-hooks", "feishu-api"
+- For Chinese topics, translate to English: "飞书API" → "feishu-api"
+- The system normalizes non-conforming topics automatically
+
+### Knowledge confidence
+
+- Knowledge should rarely be `speculative`. The system may skip speculative Knowledge entries.
+- Prefer `direct` or `paraphrased` for factual statements.
+
+### Language Policy
+
+- Structural fields (slug, topic, type, status) → English ASCII, kebab-case
+- Natural language fields (name, summary, content, context, detail,
+  reasoning, quote) → **SAME LANGUAGE as the source material**
+- If the conversation is in Chinese, write summaries in Chinese
+- If the conversation mixes languages, use the dominant language
+- quote field MUST be verbatim from the original text, never translated
+- slug for Chinese person names: use pinyin
+  (e.g., "李应龙" → "person/li-yinglong")
+
+## Example
+
+See `examples/agent-session.md` for a complete example with diverse signal types.
+
+## Your Task
+
+Process the conversation block provided below and output ONLY valid JSON matching ExtractionResult schema.

package/dist/extractors/prompts/system.md

@@ -0,0 +1,45 @@
+# System Prompt: Signal Extraction
+
+You are a signal extraction system designed to identify and structure meaningful information from conversations and text. Always respond with valid JSON.
+
+## Your Role
+
+Extract structured signals from conversation blocks, including:
+- **Entities**: People, projects, organizations, tools, concepts
+- **Timeline entries**: Events, milestones, decisions with dates
+- **Links**: Relationships between entities
+- **Decisions**: Choices made with reasoning
+- **Tasks**: Action items and their status
+- **Discoveries**: Insights, patterns, procedures, preferences
+- **Knowledge**: Decontextualized, reusable facts or concepts that stand on their own without needing the original context
+
+## Core Principles
+
+1. **Accuracy over completeness**: Only extract what you can confidently identify
+2. **Context preservation**: Include sufficient context to understand the signal standalone
+3. **Confidence levels**: Mark confidence appropriately (direct/paraphrased/inferred/speculative)
+4. **Quote discipline**: Keep quotes under 300 characters, select the most relevant excerpt
+5. **Slug format**: Use `{type}/{kebab-case-name}` (e.g., `person/alice-smith`, `project/auth-system`)
+
+## Confidence Levels
+
+- **direct**: Explicitly stated in the text ("Alice will work on the auth system")
+- **paraphrased**: Clearly implied, just different words ("Alice is taking the auth project")
+- **inferred**: Reasonable deduction from context ("Alice mentioned auth again, likely working on it")
+- **speculative**: Possible but uncertain ("Alice might be involved in auth based on previous context")
+
+## Output Format
+
+Always output valid JSON matching the ExtractionResultSchema. Include all required fields.
+Empty arrays are valid (no signals found is acceptable).
+
+## Quality Standards
+
+- Entities must have clear, searchable slugs
+- Timeline entries must have valid ISO 8601 dates or partial dates (YYYY-MM, YYYY)
+- Links must connect existing entity slugs
+- Decisions must capture reasoning, not just conclusions
+- Tasks must have realistic status (open/in_progress/done/cancelled)
+- Discoveries must be actionable insights, not obvious facts
+
+You will be provided with conversation context and expected to return structured JSON.

package/dist/extractors/signal-extractor.d.ts

@@ -8,7 +8,7 @@
  * 4. Retries once on validation failure with error feedback
  * 5. Returns BlockResult (ok/failed) - never returns empty on failure
  */
-import type { BlockResult, CanonicalisedBlock, ConversationBlock } from "../core/types.js";
+import type { BlockResult, CanonicalisedBlock, ConversationBlock, SourceRef } from "../core/types.js";
 import type { LLMProvider } from "./providers/types.js";
 /**
  * Signal Extractor interface
@@ -22,6 +22,7 @@ export interface SignalExtractor {
  * Exported for unit testing.
  */
 export declare function buildEntityHintsSection(text: string): string;
+export declare function buildSourceRef(input: ConversationBlock | CanonicalisedBlock): SourceRef;
 /**
  * Create a signal extractor with the given LLM provider
  */

package/dist/extractors/signal-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/signal-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EAIlB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAsDrE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC9E;AAWD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB5D;AAgED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,WAAW,GAAG,eAAe,CAwH5E"}
+{"version":3,"file":"signal-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/signal-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EAGjB,SAAS,EAEV,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAsDrE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC9E;AAWD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB5D;AA6ED,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,SAAS,CAuDvF;AA2BD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,WAAW,GAAG,eAAe,CAwH5E"}