@rkarim08/sia 1.0.0

package/src/graph/types.ts

@@ -0,0 +1,128 @@
+// src/graph/types.ts — Graph domain interfaces for communities, episodes, and MCP results
+
+import type { PackagePath, TrustTier, UnixMs } from "@/shared/types";
+
+// ── Community types ───────────────────────────────────────────
+
+export interface Community {
+	id: string;
+	level: 0 | 1 | 2;
+	parent_id: string | null;
+	summary: string | null;
+	summary_hash: string | null;
+	member_count: number;
+	last_summary_member_count: number;
+	package_path: PackagePath;
+	created_at: UnixMs;
+	updated_at: UnixMs;
+}
+
+export interface CommunityMember {
+	community_id: string;
+	entity_id: string;
+	level: 0 | 1 | 2;
+}
+
+export interface InsertCommunityInput {
+	level: 0 | 1 | 2;
+	parent_id?: string | null;
+	package_path?: PackagePath;
+}
+
+export interface UpdateCommunityInput {
+	summary?: string | null;
+	summary_hash?: string | null;
+	member_count?: number;
+	last_summary_member_count?: number;
+}
+
+export interface CommunitySummary {
+	id: string;
+	level: 0 | 1 | 2;
+	summary: string;
+	member_count: number;
+	top_entities: Array<{ name: string; type: string }>;
+}
+
+// ── Episode types ─────────────────────────────────────────────
+
+export interface Episode {
+	id: string;
+	session_id: string;
+	ts: UnixMs;
+	type: "conversation" | "tool_use" | "file_read" | "command";
+	role: "user" | "assistant" | "tool" | null;
+	content: string;
+	tool_name: string | null;
+	file_path: string | null;
+	trust_tier: TrustTier;
+}
+
+export interface InsertEpisodeInput {
+	session_id: string;
+	type: Episode["type"];
+	role?: Episode["role"];
+	content: string;
+	tool_name?: string | null;
+	file_path?: string | null;
+	trust_tier?: TrustTier;
+}
+
+// ── MCP result types ──────────────────────────────────────────
+
+export interface SiaSearchResult {
+	entity_id: string;
+	type: string;
+	name: string;
+	summary: string;
+	content: string;
+	tags: string[];
+	file_paths: string[];
+	trust_tier: TrustTier;
+	confidence: number;
+	importance: number;
+	extraction_method?: string;
+	conflict_group_id?: string | null;
+	t_valid_from?: UnixMs | null;
+	t_valid_until?: UnixMs | null;
+	source_repo_id?: string;
+	source_repo_name?: string;
+	freshness?: "fresh" | "stale" | "rotten";
+	freshness_detail?: {
+		source_path: string;
+		source_mtime: number;
+		extraction_time: number;
+		divergence_seconds: number;
+		confidence: number;
+		alpha?: number;
+		beta?: number;
+	};
+}
+
+export interface SiaEdge {
+	id: string;
+	from_id: string;
+	to_id: string;
+	type: string;
+	weight: number;
+	confidence: number;
+}
+
+export interface SiaExpandResult {
+	center: SiaSearchResult;
+	neighbors: SiaSearchResult[];
+	edges: SiaEdge[];
+	edge_count: number;
+}
+
+export interface SiaTemporalResult {
+	entities: SiaSearchResult[];
+	invalidated_entities: SiaSearchResult[];
+	edges: SiaEdge[];
+	invalidated_count: number;
+}
+
+export interface SiaCommunityResult {
+	communities: CommunitySummary[];
+	global_unavailable: boolean;
+}

package/src/hooks/adapters/claude-code.ts

@@ -0,0 +1,21 @@
+// src/hooks/adapters/claude-code.ts — Native Claude Code adapter (identity mapping)
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { HookEvent } from "@/hooks/types";
+
+/**
+ * Claude Code adapter — identity mapping, no transformation needed.
+ * Claude Code emits events that already match Sia's HookEvent format exactly.
+ */
+export function normalizeClaudeCodeEvent(raw: Record<string, unknown>): HookEvent {
+	return raw as unknown as HookEvent;
+}
+
+/**
+ * Detect whether the current project is using Claude Code.
+ * Looks for the .claude/ directory created by `claude` CLI initialization.
+ */
+export function detectClaudeCode(cwd: string): boolean {
+	return existsSync(join(cwd, ".claude"));
+}

package/src/hooks/adapters/cline.ts

@@ -0,0 +1,43 @@
+// src/hooks/adapters/cline.ts — Cline hook adapter
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { HookEvent } from "@/hooks/types";
+
+/**
+ * Tool name mapping from Cline's conventions to Claude Code conventions.
+ * Cline uses snake_case tool names; Claude Code uses PascalCase.
+ */
+const CLINE_TOOL_NAME_MAP: Record<string, string> = {
+	write_to_file: "Write",
+	read_file: "Read",
+	list_files: "LS",
+	search_files: "Grep",
+	execute_command: "Bash",
+	browser_action: "WebFetch",
+	ask_followup_question: "Ask",
+	attempt_completion: "TodoWrite",
+};
+
+/**
+ * Cline hooks are nearly identical to Claude Code — thin mapping.
+ * The main difference is Cline uses snake_case tool names vs Claude Code's PascalCase.
+ */
+export function normalizeClineEvent(raw: Record<string, unknown>): HookEvent {
+	const normalized = { ...raw } as Record<string, unknown>;
+
+	// Normalize Cline snake_case tool names to Claude Code PascalCase
+	if (typeof raw.tool_name === "string") {
+		normalized.tool_name = CLINE_TOOL_NAME_MAP[raw.tool_name] ?? raw.tool_name;
+	}
+
+	return normalized as unknown as HookEvent;
+}
+
+/**
+ * Detect whether the current project is using Cline.
+ * Looks for the .clinerules/ directory used by Cline for custom instructions.
+ */
+export function detectCline(cwd: string): boolean {
+	return existsSync(join(cwd, ".clinerules"));
+}

package/src/hooks/adapters/cursor.ts

@@ -0,0 +1,65 @@
+// src/hooks/adapters/cursor.ts — Cursor hook adapter
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { HookEvent } from "@/hooks/types";
+
+/** Cursor's native hook event shape */
+interface CursorHookEvent {
+	event: "afterFileEdit" | "afterModelResponse" | "beforeSubmitPrompt";
+	filePath?: string;
+	content?: string;
+	response?: string;
+}
+
+/**
+ * Map Cursor hook events to Sia's HookEvent format.
+ *
+ * Cursor event → Claude Code HookEvent mapping:
+ *   afterFileEdit       → PostToolUse (tool_name: Write)
+ *   afterModelResponse  → Stop
+ *   beforeSubmitPrompt  → UserPromptSubmit
+ */
+export function normalizeCursorEvent(raw: CursorHookEvent): HookEvent {
+	const base: Partial<HookEvent> = {
+		session_id: "",
+		transcript_path: "",
+		cwd: "",
+	};
+
+	switch (raw.event) {
+		case "afterFileEdit":
+			return {
+				...base,
+				hook_event_name: "PostToolUse",
+				tool_name: "Write",
+				tool_input: raw.filePath
+					? {
+							file_path: raw.filePath,
+							content: raw.content ?? "",
+						}
+					: undefined,
+			} as HookEvent;
+
+		case "afterModelResponse":
+			return {
+				...base,
+				hook_event_name: "Stop",
+				reason: "exit",
+			} as HookEvent;
+
+		case "beforeSubmitPrompt":
+			return {
+				...base,
+				hook_event_name: "UserPromptSubmit",
+			} as HookEvent;
+	}
+}
+
+/**
+ * Detect whether the current project is using Cursor.
+ * Looks for the .cursor/ directory created by Cursor IDE.
+ */
+export function detectCursor(cwd: string): boolean {
+	return existsSync(join(cwd, ".cursor"));
+}

package/src/hooks/adapters/generic.ts

@@ -0,0 +1,12 @@
+// src/hooks/adapters/generic.ts — Fallback adapter for agents without hook systems
+
+import type { CaptureMode } from "@/llm/provider-registry";
+
+/**
+ * For agents without hook systems (Windsurf, Aider, etc.), fall back to api
+ * capture mode. In api mode, Sia periodically polls or processes transcripts
+ * via direct LLM calls rather than relying on event hooks.
+ */
+export function getGenericCaptureMode(): CaptureMode {
+	return "api";
+}

package/src/hooks/agent-detect.ts

@@ -0,0 +1,34 @@
+// src/hooks/agent-detect.ts — Auto-detection of AI coding agents
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { CaptureMode } from "@/llm/provider-registry";
+
+/** Known AI coding agents that Sia can integrate with */
+export type DetectedAgent = "claude-code" | "cursor" | "cline" | "generic";
+
+/**
+ * Detect which AI agent is active based on directory markers.
+ * Used by `npx sia install` to configure appropriate hooks.
+ *
+ * Detection order (precedence):
+ *   1. .claude/        → claude-code
+ *   2. .cursor/        → cursor
+ *   3. .clinerules/    → cline
+ *   4. (none found)    → generic
+ */
+export function detectAgent(cwd: string): DetectedAgent {
+	if (existsSync(join(cwd, ".claude"))) return "claude-code";
+	if (existsSync(join(cwd, ".cursor"))) return "cursor";
+	if (existsSync(join(cwd, ".clinerules"))) return "cline";
+	return "generic";
+}
+
+/**
+ * Get the recommended capture mode for the detected agent.
+ * Agents with hook systems use "hooks" mode; those without use "api" mode.
+ */
+export function getRecommendedCaptureMode(agent: DetectedAgent): CaptureMode {
+	if (agent === "generic") return "api";
+	return "hooks";
+}

package/src/hooks/claude-md-directives.ts

@@ -0,0 +1,32 @@
+// Module: claude-md-directives — Behavioral directives for proactive knowledge capture
+//
+// This string constant is injected into CLAUDE.md to guide the agent toward
+// capturing decisions, conventions, bugs, and solutions during coding sessions.
+
+/**
+ * CLAUDE.md behavioral directives that instruct the agent to proactively
+ * capture knowledge into Sia's persistent graph memory.
+ *
+ * Include this block in the project's CLAUDE.md to enable session-aware
+ * knowledge capture.
+ */
+export const KNOWLEDGE_DIRECTIVES = `## Sia Knowledge Management
+
+When you make decisions during coding:
+- After choosing between architectural alternatives, call mcp__sia__note with
+  kind='Decision', including your reasoning and the alternatives you considered.
+- When you establish or recognize a coding pattern the team should follow,
+  call mcp__sia__note with kind='Convention'.
+- When you discover a bug's root cause, call mcp__sia__note with kind='Bug'
+  and reference the affected files.
+- When you fix a bug, call mcp__sia__note with kind='Solution' and reference
+  the Bug it resolves.
+
+Before starting work:
+- Call mcp__sia__search to check for relevant prior knowledge about the files
+  and symbols you'll be working with.
+
+These calls help build persistent memory that survives across sessions.
+You don't need to capture every small edit — focus on decisions, patterns,
+and discoveries that a future developer (or your future self) would want to know.
+`;

package/src/hooks/event-router.ts

@@ -0,0 +1,182 @@
+// src/hooks/event-router.ts — HTTP hook endpoint server
+//
+// Runs alongside the MCP stdio server. Receives hook events from Claude Code
+// as HTTP POST requests and dispatches to the appropriate handler.
+//
+// PostToolUse hooks run async (non-blocking). Stop and PreCompact run sync.
+// SessionStart uses a command hook (not HTTP) — handled separately.
+//
+// Uses node:http for cross-runtime compatibility (Bun + Node/Vitest).
+
+import { createServer, type Server } from "node:http";
+import type { HookEvent, HookHandler, HookResponse } from "./types";
+
+const DEFAULT_PORT = 4521;
+
+/** Registry of hook handlers by event name */
+const handlers: Record<string, HookHandler> = {};
+
+/**
+ * Register a handler for a hook event name.
+ * Event names: "post-tool-use", "stop", "pre-compact", "post-compact",
+ *              "session-start", "session-end", "user-prompt-submit"
+ */
+export function registerHandler(eventName: string, handler: HookHandler): void {
+	handlers[eventName] = handler;
+}
+
+/**
+ * Get a registered handler. Returns undefined if not found.
+ */
+export function getHandler(eventName: string): HookHandler | undefined {
+	return handlers[eventName];
+}
+
+/**
+ * Clear all registered handlers (for testing).
+ */
+export function clearHandlers(): void {
+	for (const key of Object.keys(handlers)) {
+		delete handlers[key];
+	}
+}
+
+/** Read the full request body as a string. */
+function readBody(req: import("node:http").IncomingMessage): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		req.on("data", (chunk: Buffer) => chunks.push(chunk));
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+		req.on("error", reject);
+	});
+}
+
+/** Send a JSON response. */
+function sendJson(res: import("node:http").ServerResponse, status: number, body: unknown): void {
+	const json = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json",
+		"Content-Length": Buffer.byteLength(json),
+	});
+	res.end(json);
+}
+
+/**
+ * Start the HTTP hook event server.
+ * Returns a server object that can be stopped.
+ */
+export function startHookServer(port: number = DEFAULT_PORT): {
+	port: number;
+	stop: () => void;
+} {
+	const server: Server = createServer(async (req, res) => {
+		const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+
+		// Health check
+		if (url.pathname === "/health") {
+			sendJson(res, 200, {
+				status: "ok",
+				handlers: Object.keys(handlers),
+			});
+			return;
+		}
+
+		// Hook dispatch: /hooks/<event-name>
+		const match = url.pathname.match(/^\/hooks\/(.+)$/);
+		if (!match) {
+			res.writeHead(404);
+			res.end("Not found");
+			return;
+		}
+
+		const eventName = match[1];
+		const handler = handlers[eventName];
+		if (!handler) {
+			sendJson(res, 404, {
+				status: "error",
+				error: `No handler for event: ${eventName}`,
+			} satisfies HookResponse);
+			return;
+		}
+
+		try {
+			const body = await readBody(req);
+			const event: HookEvent = JSON.parse(body);
+			const response = await handler(event);
+			sendJson(res, 200, response);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			sendJson(res, 500, {
+				status: "error",
+				error: message,
+			} satisfies HookResponse);
+		}
+	});
+
+	server.listen(port);
+
+	// Resolve the actual port (important when port=0 for random assignment)
+	const addr = server.address();
+	const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
+
+	return {
+		port: actualPort,
+		stop: () => server.close(),
+	};
+}
+
+/**
+ * Get the hook configuration for .claude/settings.json.
+ * Used by `npx sia install` to register hooks.
+ */
+export function getHookConfig(port: number = DEFAULT_PORT): Record<string, unknown[]> {
+	return {
+		PostToolUse: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/post-tool-use`,
+				timeout: 5000,
+				async: true,
+			},
+		],
+		Stop: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/stop`,
+				timeout: 10000,
+			},
+		],
+		PreCompact: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/pre-compact`,
+				timeout: 5000,
+			},
+		],
+		PostCompact: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/post-compact`,
+				timeout: 5000,
+				async: true,
+			},
+		],
+		SessionStart: [{ type: "command", command: "npx sia hook session-start" }],
+		SessionEnd: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/session-end`,
+				timeout: 5000,
+				async: true,
+			},
+		],
+		UserPromptSubmit: [
+			{
+				type: "http",
+				url: `http://localhost:${port}/hooks/user-prompt-submit`,
+				timeout: 5000,
+				async: true,
+			},
+		],
+	};
+}

package/src/hooks/extractors/pattern-detector.ts

@@ -0,0 +1,111 @@
+// Module: pattern-detector — Deterministic knowledge pattern detection (zero LLM)
+//
+// Scans text for structured knowledge markers: decisions, conventions, bugs,
+// concepts, and solutions. Used by PostToolUse and Stop handlers to extract
+// knowledge without requiring an LLM call.
+
+import type { EntityType } from "@/capture/types";
+
+/** A knowledge pattern detected in text content. */
+export interface DetectedPattern {
+	type: EntityType;
+	content: string;
+	confidence: number;
+	/** The line that matched, for dedup downstream. */
+	matchedLine: string;
+}
+
+// ---------------------------------------------------------------------------
+// Content pattern rules — each rule maps a regex to an entity type
+// ---------------------------------------------------------------------------
+
+interface PatternRule {
+	type: EntityType;
+	pattern: RegExp;
+	confidence: number;
+}
+
+const CONTENT_RULES: PatternRule[] = [
+	// Decision markers
+	{ type: "Decision", pattern: /\bwe decided\b/i, confidence: 0.85 },
+	{ type: "Decision", pattern: /\bchose\s+\S+\s+over\b/i, confidence: 0.8 },
+	{ type: "Decision", pattern: /\bdecision:\s*/i, confidence: 0.9 },
+
+	// Convention markers
+	{ type: "Convention", pattern: /\bconvention:\s*/i, confidence: 0.9 },
+	{ type: "Convention", pattern: /\balways use\b/i, confidence: 0.7 },
+	{ type: "Convention", pattern: /\bnever use\b/i, confidence: 0.7 },
+
+	// Bug markers
+	{ type: "Bug", pattern: /\bBUG:\s*/i, confidence: 0.9 },
+	{ type: "Bug", pattern: /\bFIXME:\s*/i, confidence: 0.85 },
+	{ type: "Bug", pattern: /\bHACK:\s*/i, confidence: 0.8 },
+
+	// Concept markers
+	{ type: "Concept", pattern: /\bTODO:\s*/i, confidence: 0.75 },
+	{ type: "Concept", pattern: /\bREFACTOR:\s*/i, confidence: 0.75 },
+];
+
+// ---------------------------------------------------------------------------
+// Commit message pattern rules
+// ---------------------------------------------------------------------------
+
+const COMMIT_RULES: PatternRule[] = [
+	{ type: "Solution", pattern: /^fix(\(.+?\))?:\s*/i, confidence: 0.85 },
+	{ type: "Decision", pattern: /^feat(\(.+?\))?:\s*/i, confidence: 0.75 },
+	{ type: "Decision", pattern: /^refactor(\(.+?\))?:\s*/i, confidence: 0.7 },
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan free-form content for knowledge patterns.
+ * Processes line-by-line to attribute each match to the originating line.
+ * Returns one DetectedPattern per match (a single line may yield multiple).
+ */
+export function detectKnowledgePatterns(content: string): DetectedPattern[] {
+	const results: DetectedPattern[] = [];
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0) continue;
+
+		for (const rule of CONTENT_RULES) {
+			if (rule.pattern.test(trimmed)) {
+				results.push({
+					type: rule.type,
+					content: trimmed,
+					confidence: rule.confidence,
+					matchedLine: trimmed,
+				});
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Scan a conventional commit message for knowledge patterns.
+ * Recognizes fix/feat/refactor prefixes.
+ */
+export function detectCommitPatterns(message: string): DetectedPattern[] {
+	const results: DetectedPattern[] = [];
+	const trimmed = message.trim();
+
+	for (const rule of COMMIT_RULES) {
+		if (rule.pattern.test(trimmed)) {
+			results.push({
+				type: rule.type,
+				content: trimmed,
+				confidence: rule.confidence,
+				matchedLine: trimmed,
+			});
+		}
+	}
+
+	return results;
+}

package/src/hooks/handlers/post-compact.ts

@@ -0,0 +1,30 @@
+// Module: post-compact — PostCompact hook handler
+//
+// Fires after Claude Code has compacted the context window. This is a
+// lightweight handler — the compaction has already occurred, so there is
+// nothing to capture at this point. Instead, it logs compaction coverage
+// info for observability.
+//
+// Returns { status: "processed", compact_summary_length: N } where N is
+// the character length of the compaction summary provided by Claude Code.
+
+import type { HookEvent, HookResponse } from "@/hooks/types";
+
+/**
+ * Create a PostCompact hook handler.
+ *
+ * Lightweight — logs compaction coverage info and returns immediately.
+ * No database writes are performed; knowledge should have been captured
+ * by the PreCompact handler before compaction occurred.
+ */
+export function createPostCompactHandler(): (event: HookEvent) => Promise<HookResponse> {
+	return async (event: HookEvent): Promise<HookResponse> => {
+		const compactSummary = event.compact_summary ?? "";
+		const summaryLength = compactSummary.length;
+
+		return {
+			status: "processed",
+			compact_summary_length: summaryLength,
+		};
+	};
+}