zam-core 0.7.2 → 0.8.0

package/dist/index.d.ts

@@ -537,9 +537,10 @@ declare function deleteCardForUser(db: Database, tokenId: string, userId: string
  *
  * Ported from the PoC's due-tokens command.
  *
- * When `domain` is set, only due cards in that token domain are returned.
+ * When `domain` or `knowledgeContext` is set, only matching due cards are
+ * returned.
  */
-declare function getDueCards(db: Database, userId: string, now?: string, domain?: string): Promise<DueCard[]>;
+declare function getDueCards(db: Database, userId: string, now?: string, domain?: string, knowledgeContext?: string): Promise<DueCard[]>;
 /**
  * Get all blocked cards for a user.
  *
@@ -548,6 +549,68 @@ declare function getDueCards(db: Database, userId: string, now?: string, domain?
  */
 declare function getBlockedCards(db: Database, userId: string): Promise<BlockedCard[]>;
 
+/**
+ * Knowledge Context repository — typed wrappers around the contexts and token_contexts tables.
+ *
+ * A context represents a first-class facet (e.g. work, school, private) that can have
+ * attributes like default generation language.
+ */
+
+interface KnowledgeContext {
+    id: string;
+    name: string;
+    label: string | null;
+    language: string | null;
+    created_at: string;
+}
+interface CreateKnowledgeContextInput {
+    name: string;
+    label?: string | null;
+    language?: string | null;
+}
+interface UpdateKnowledgeContextInput {
+    name?: string;
+    label?: string | null;
+    language?: string | null;
+}
+/**
+ * Create a new knowledge context.
+ */
+declare function createKnowledgeContext(db: Database, input: CreateKnowledgeContextInput): Promise<KnowledgeContext>;
+/**
+ * Retrieve a knowledge context by its unique name.
+ */
+declare function getKnowledgeContextByName(db: Database, name: string): Promise<KnowledgeContext | undefined>;
+/**
+ * Retrieve a knowledge context by its ULID.
+ */
+declare function getKnowledgeContextById(db: Database, id: string): Promise<KnowledgeContext | undefined>;
+/**
+ * List all knowledge contexts ordered by creation date (oldest first) or name.
+ */
+declare function listKnowledgeContexts(db: Database): Promise<KnowledgeContext[]>;
+/**
+ * Update mutable fields on a knowledge context.
+ */
+declare function updateKnowledgeContext(db: Database, id: string, updates: UpdateKnowledgeContextInput): Promise<KnowledgeContext>;
+/**
+ * Delete a knowledge context. Cascades deletion of associated token mappings.
+ */
+declare function deleteKnowledgeContext(db: Database, id: string): Promise<void>;
+/**
+ * Assign a token to a knowledge context.
+ * Safe to call repeatedly (noop if already assigned).
+ */
+declare function assignTokenToContext(db: Database, tokenId: string, contextId: string): Promise<void>;
+/**
+ * Remove a token from a knowledge context.
+ */
+declare function unassignTokenFromContext(db: Database, tokenId: string, contextId: string): Promise<void>;
+/**
+ * List all knowledge contexts assigned to a given token.
+ */
+declare function listContextsForToken(db: Database, tokenId: string): Promise<KnowledgeContext[]>;
+
 /**
  * Prerequisite repository — typed wrappers around the prerequisites table.
  *
@@ -846,10 +909,14 @@ interface UpdateTokenInput {
 interface ListTokensOptions {
     domain?: string;
     /**
-     * Filter by domain prefix using `/` as separator (e.g. "docuware-cops").
+     * Filter by domain prefix using `/` as separator (e.g. "company-team").
      * Matches exact or startsWith(prefix + "/").
      */
     domainPrefix?: string;
+    /**
+     * Filter by knowledge context name (e.g. "work-company").
+     */
+    knowledgeContext?: string;
 }
 interface TokenDeleteImpact {
     cards: number;
@@ -918,8 +985,8 @@ declare function deleteToken(db: Database, slug: string): Promise<DeleteTokenRes
  */
 declare function findTokens(db: Database, query: string): Promise<ScoredToken[]>;
 /**
- * List all tokens, optionally filtered by domain.
- * Results are ordered by bloom_level then slug.
+ * List all tokens, optionally filtered by domain or knowledge context.
+ * Results are ordered by bloom_level then domain then slug (or bloom_level then slug if domain-filtered).
  */
 declare function listTokens(db: Database, options?: ListTokensOptions): Promise<Token[]>;
 interface PersonalCard {
@@ -965,6 +1032,7 @@ declare function generateTokenSlug(db: Database, domain: string, concept: string
 declare function listPersonalCards(db: Database, userId: string, options?: {
     query?: string;
     domain?: string;
+    knowledgeContext?: string;
 }): Promise<PersonalCard[]>;
 interface CurriculumCardInput {
     question: string;
@@ -1878,6 +1946,7 @@ interface ReviewQueueOptions {
     maxNew?: number;
     maxReviews?: number;
     now?: Date;
+    knowledgeContext?: string;
 }
 interface ReviewQueueItem {
     cardId: string;
@@ -2131,6 +2200,7 @@ interface WorkspaceConfig {
     sourceControl?: WorkspaceSourceControl;
     knowledgeScopes?: string[];
     defaultAgent?: string;
+    activeKnowledgeContext?: string;
 }
 /** Load ~/.zam/config.json. Returns an empty config if missing or unreadable. */
 declare function loadInstallConfig(path?: string): InstallConfig;
@@ -2165,6 +2235,8 @@ declare function removeConfiguredWorkspace(id: string, path?: string): Workspace
  * good for moving snapshots between machines"), never for behavior.
  */
 declare function detectSyncProvider(dir: string): string | null;
+declare function getActiveWorkspaceContext(path?: string): string | undefined;
+declare function setActiveWorkspaceContext(contextName: string | undefined, path?: string): boolean;
 
 interface InstallResult {
     success: boolean;
@@ -2262,4 +2334,4 @@ declare function resolveAllBeliefPaths(db: Database): Promise<string[]>;
  */
 declare function resolveAllGoalPaths(db: Database): Promise<string[]>;
 
-export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, BUILT_IN_SENSITIVE_MATCHERS, type BloomLevel$1 as BloomLevel, type CaptureDecision, type CaptureDenialReason, type CaptureRequest, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, DEFAULT_OBSERVER_POLICY, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseTargetInfo, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type FoundationSuggestion, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type ListTokensOptions, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, type MonitorEvent, type Neighborhood, type NeighborhoodToken, OBSERVER_POLICY_UNSET_HINT, OBSERVER_POLICY_VERSION, type ObservationRating, type ObserverConsent, type ObserverPolicy, type ObserverRetention, type ObserverScope, type ObserverSettingKey, type OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedCaptureTarget, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SIDECAR_POLICY_FILE, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SidecarPrivacyPolicy, type SkillProposal, type SkillSource, type SnapshotManifest, type SourceProposalInput, type SplitProposalInput, type Statement, type SuggestFoundationsOptions, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildAncestorMap, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDisplayTitle, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getShortSlug, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listEmbeddedTokens, listGoals, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchBuiltInSensitive, matchDenylist, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseObserverList, parseObserverPolicy, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, planUpdate, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, suggestFoundations, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, verifySnapshot, wouldCreateCycle, writeMonitorEvent };
+export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, BUILT_IN_SENSITIVE_MATCHERS, type BloomLevel$1 as BloomLevel, type CaptureDecision, type CaptureDenialReason, type CaptureRequest, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateKnowledgeContextInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, DEFAULT_OBSERVER_POLICY, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseTargetInfo, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type FoundationSuggestion, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type KnowledgeContext, type ListTokensOptions, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, type MonitorEvent, type Neighborhood, type NeighborhoodToken, OBSERVER_POLICY_UNSET_HINT, OBSERVER_POLICY_VERSION, type ObservationRating, type ObserverConsent, type ObserverPolicy, type ObserverRetention, type ObserverScope, type ObserverSettingKey, type OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedCaptureTarget, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SIDECAR_POLICY_FILE, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SidecarPrivacyPolicy, type SkillProposal, type SkillSource, type SnapshotManifest, type SourceProposalInput, type SplitProposalInput, type Statement, type SuggestFoundationsOptions, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateKnowledgeContextInput, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, assignTokenToContext, buildAncestorMap, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createKnowledgeContext, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteKnowledgeContext, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceContext, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDisplayTitle, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getKnowledgeContextById, getKnowledgeContextByName, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getShortSlug, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listContextsForToken, listEmbeddedTokens, listGoals, listKnowledgeContexts, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchBuiltInSensitive, matchDenylist, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseObserverList, parseObserverPolicy, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, planUpdate, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceContext, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, suggestFoundations, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unassignTokenFromContext, unblockReady, updateCard, updateGoalStatus, updateKnowledgeContext, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, verifySnapshot, wouldCreateCycle, writeMonitorEvent };

package/dist/index.js

@@ -669,6 +669,22 @@ CREATE TABLE IF NOT EXISTS agent_skills (
   updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+-- Knowledge contexts: work, school, private
+CREATE TABLE IF NOT EXISTS contexts (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL UNIQUE,
+  label      TEXT,
+  language   TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Join table mapping tokens to their knowledge contexts
+CREATE TABLE IF NOT EXISTS token_contexts (
+  token_id   TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+  context_id TEXT NOT NULL REFERENCES contexts(id) ON DELETE CASCADE,
+  PRIMARY KEY (token_id, context_id)
+);
+
 -- Performance indexes
 CREATE INDEX IF NOT EXISTS idx_tokens_domain ON tokens(domain);
 CREATE INDEX IF NOT EXISTS idx_tokens_slug ON tokens(slug);
@@ -680,7 +696,7 @@ CREATE INDEX IF NOT EXISTS idx_review_logs_card ON review_logs(card_id);
 CREATE INDEX IF NOT EXISTS idx_review_logs_user ON review_logs(user_id, reviewed_at);
 CREATE INDEX IF NOT EXISTS idx_session_steps_session ON session_steps(session_id);
 CREATE INDEX IF NOT EXISTS idx_tokens_title ON tokens(title);
-CREATE INDEX IF NOT EXISTS idx_tokens_domain ON tokens(domain);
+CREATE INDEX IF NOT EXISTS idx_token_contexts_context ON token_contexts(context_id);
 `;
 
 // src/kernel/db/sync-adapter.ts
@@ -1023,6 +1039,25 @@ async function runMigrations(db) {
   await db.exec(
     `CREATE INDEX IF NOT EXISTS idx_tokens_domain ON tokens(domain)`
   );
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS contexts (
+      id         TEXT PRIMARY KEY,
+      name       TEXT NOT NULL UNIQUE,
+      label      TEXT,
+      language   TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS token_contexts (
+      token_id   TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+      context_id TEXT NOT NULL REFERENCES contexts(id) ON DELETE CASCADE,
+      PRIMARY KEY (token_id, context_id)
+    )
+  `);
+  await db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_token_contexts_context ON token_contexts(context_id)
+  `);
 }
 
 // src/kernel/db/snapshot.ts
@@ -1486,24 +1521,27 @@ async function deleteCardForUser(db, tokenId, userId) {
   await db.prepare("DELETE FROM cards WHERE id = ?").run(card.id);
   return { card, impact };
 }
-async function getDueCards(db, userId, now, domain) {
+async function getDueCards(db, userId, now, domain, knowledgeContext) {
   const cutoff = now ?? (/* @__PURE__ */ new Date()).toISOString();
+  let sql = `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
+    FROM cards c
+    JOIN tokens t ON t.id = c.token_id
+    WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ?`;
+  const params = [userId, cutoff];
   if (domain) {
-    return await db.prepare(
-      `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
-         FROM cards c
-         JOIN tokens t ON t.id = c.token_id
-         WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ? AND t.domain = ?
-         ORDER BY t.bloom_level ASC, c.due_at ASC`
-    ).all(userId, cutoff, domain);
+    sql += " AND t.domain = ?";
+    params.push(domain);
   }
-  return await db.prepare(
-    `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ?
-       ORDER BY t.bloom_level ASC, c.due_at ASC`
-  ).all(userId, cutoff);
+  if (knowledgeContext) {
+    sql += ` AND EXISTS (
+      SELECT 1 FROM token_contexts tc
+      INNER JOIN contexts context_filter ON context_filter.id = tc.context_id
+      WHERE tc.token_id = t.id AND context_filter.name = ?
+    )`;
+    params.push(knowledgeContext);
+  }
+  sql += " ORDER BY t.bloom_level ASC, c.due_at ASC";
+  return await db.prepare(sql).all(...params);
 }
 async function getBlockedCards(db, userId) {
   return await db.prepare(
@@ -1515,11 +1553,116 @@ async function getBlockedCards(db, userId) {
   ).all(userId);
 }
 
-// src/kernel/models/token.ts
+// src/kernel/models/knowledge-context.ts
 import { ulid as ulid3 } from "ulid";
-async function createToken(db, input) {
+function normalizeContextName(name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("Context name cannot be empty");
+  }
+  return normalized;
+}
+function normalizeOptionalText(value) {
+  if (value == null) return null;
+  const normalized = value.trim();
+  return normalized || null;
+}
+async function createKnowledgeContext(db, input) {
   const id = ulid3();
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  const name = normalizeContextName(input.name);
+  const existing = await getKnowledgeContextByName(db, name);
+  if (existing) {
+    throw new Error(`Knowledge context with name "${name}" already exists`);
+  }
+  await db.prepare(
+    `INSERT INTO contexts (id, name, label, language, created_at)
+       VALUES (?, ?, ?, ?, ?)`
+  ).run(
+    id,
+    name,
+    normalizeOptionalText(input.label),
+    normalizeOptionalText(input.language),
+    now
+  );
+  const context = await getKnowledgeContextById(db, id);
+  if (!context) {
+    throw new Error(
+      `Failed to retrieve newly created knowledge context: ${id}`
+    );
+  }
+  return context;
+}
+async function getKnowledgeContextByName(db, name) {
+  const normalized = name.trim();
+  if (!normalized) return void 0;
+  return await db.prepare("SELECT * FROM contexts WHERE name = ?").get(normalized);
+}
+async function getKnowledgeContextById(db, id) {
+  return await db.prepare("SELECT * FROM contexts WHERE id = ?").get(id);
+}
+async function listKnowledgeContexts(db) {
+  return await db.prepare("SELECT * FROM contexts ORDER BY name ASC").all();
+}
+async function updateKnowledgeContext(db, id, updates) {
+  const context = await getKnowledgeContextById(db, id);
+  if (!context) {
+    throw new Error(`Knowledge context not found: ${id}`);
+  }
+  const fields = [];
+  const values = [];
+  if (updates.name !== void 0) {
+    const name = normalizeContextName(updates.name);
+    if (name !== context.name) {
+      const existing = await getKnowledgeContextByName(db, name);
+      if (existing) {
+        throw new Error(`Knowledge context with name "${name}" already exists`);
+      }
+      fields.push("name = ?");
+      values.push(name);
+    }
+  }
+  if (updates.label !== void 0) {
+    fields.push("label = ?");
+    values.push(normalizeOptionalText(updates.label));
+  }
+  if (updates.language !== void 0) {
+    fields.push("language = ?");
+    values.push(normalizeOptionalText(updates.language));
+  }
+  if (fields.length === 0) {
+    return context;
+  }
+  values.push(id);
+  await db.prepare(`UPDATE contexts SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+  return await getKnowledgeContextById(db, id);
+}
+async function deleteKnowledgeContext(db, id) {
+  await db.prepare("DELETE FROM contexts WHERE id = ?").run(id);
+}
+async function assignTokenToContext(db, tokenId, contextId) {
+  await db.prepare(
+    `INSERT OR IGNORE INTO token_contexts (token_id, context_id)
+       VALUES (?, ?)`
+  ).run(tokenId, contextId);
+}
+async function unassignTokenFromContext(db, tokenId, contextId) {
+  await db.prepare("DELETE FROM token_contexts WHERE token_id = ? AND context_id = ?").run(tokenId, contextId);
+}
+async function listContextsForToken(db, tokenId) {
+  return await db.prepare(
+    `SELECT c.* FROM contexts c
+       INNER JOIN token_contexts tc ON tc.context_id = c.id
+       WHERE tc.token_id = ?
+       ORDER BY c.name ASC`
+  ).all(tokenId);
+}
+
+// src/kernel/models/token.ts
+import { ulid as ulid4 } from "ulid";
+async function createToken(db, input) {
+  const id = ulid4();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
   const bloom = input.bloom_level ?? 1;
   if (bloom < 1 || bloom > 5) {
     throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
@@ -1755,21 +1898,27 @@ async function findTokens(db, query) {
   return scored;
 }
 async function listTokens(db, options) {
-  let tokens;
+  const whereClauses = ["deprecated_at IS NULL"];
+  const params = [];
   if (options?.domain) {
-    tokens = await db.prepare(
-      "SELECT * FROM tokens WHERE domain = ? AND deprecated_at IS NULL ORDER BY bloom_level, slug"
-    ).all(options.domain);
+    whereClauses.push("domain = ?");
+    params.push(options.domain);
   } else if (options?.domainPrefix) {
     const prefix = options.domainPrefix;
-    tokens = await db.prepare(
-      `SELECT * FROM tokens WHERE (domain = ? OR domain LIKE ?) AND deprecated_at IS NULL ORDER BY bloom_level, slug`
-    ).all(prefix, `${prefix}/%`);
-  } else {
-    tokens = await db.prepare(
-      "SELECT * FROM tokens WHERE deprecated_at IS NULL ORDER BY bloom_level, domain, slug"
-    ).all();
-  }
+    whereClauses.push("(domain = ? OR domain LIKE ?)");
+    params.push(prefix, `${prefix}/%`);
+  }
+  if (options?.knowledgeContext) {
+    whereClauses.push(`EXISTS (
+      SELECT 1 FROM token_contexts tc
+      INNER JOIN contexts c ON c.id = tc.context_id
+      WHERE tc.token_id = tokens.id AND c.name = ?
+    )`);
+    params.push(options.knowledgeContext);
+  }
+  const orderBy = options?.domain || options?.domainPrefix ? "ORDER BY bloom_level, slug" : "ORDER BY bloom_level, domain, slug";
+  const sql = `SELECT * FROM tokens WHERE ${whereClauses.join(" AND ")} ${orderBy}`;
+  const tokens = await db.prepare(sql).all(...params);
   for (const token of tokens) {
     parseTokenFallback(token);
   }
@@ -1860,6 +2009,14 @@ async function listPersonalCards(db, userId, options) {
     sql += " AND t.domain = ?";
     values.push(options.domain);
   }
+  if (options?.knowledgeContext) {
+    sql += ` AND EXISTS (
+      SELECT 1 FROM token_contexts tc
+      INNER JOIN contexts kc ON kc.id = tc.context_id
+      WHERE tc.token_id = t.id AND kc.name = ?
+    )`;
+    values.push(options.knowledgeContext);
+  }
   if (options?.query) {
     const terms = options.query.toLowerCase().split(/\s+/).filter(Boolean);
     for (const term of terms) {
@@ -2385,12 +2542,12 @@ async function getTokenNeighborhood(db, tokenId, userId) {
 }
 
 // src/kernel/models/review.ts
-import { ulid as ulid4 } from "ulid";
+import { ulid as ulid5 } from "ulid";
 async function logReview(db, input) {
   if (input.rating < 1 || input.rating > 4) {
     throw new Error(`Rating must be between 1 and 4, got ${input.rating}`);
   }
-  const id = ulid4();
+  const id = ulid5();
   const now = (/* @__PURE__ */ new Date()).toISOString();
   await db.prepare(
     `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
@@ -2433,9 +2590,9 @@ async function getReviewsForUser(db, userId, options) {
 }
 
 // src/kernel/models/session.ts
-import { ulid as ulid5 } from "ulid";
+import { ulid as ulid6 } from "ulid";
 async function startSession(db, input) {
-  const id = ulid5();
+  const id = ulid6();
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const ctx = input.execution_context ?? "shell";
   await db.prepare(
@@ -2469,7 +2626,7 @@ async function logStep(db, input) {
   if (!session) {
     throw new Error(`Session not found: ${input.session_id}`);
   }
-  const id = ulid5();
+  const id = ulid6();
   const now = (/* @__PURE__ */ new Date()).toISOString();
   await db.prepare(
     `INSERT INTO session_steps (id, session_id, token_id, done_by, rating, notes, created_at)
@@ -3368,10 +3525,10 @@ async function syncObserverSidecarPolicy(db, dir = getUiObserverDir()) {
 }
 
 // src/kernel/observation/session-synthesis.ts
-import { ulid as ulid7 } from "ulid";
+import { ulid as ulid8 } from "ulid";
 
 // src/kernel/recall/evaluator.ts
-import { ulid as ulid6 } from "ulid";
+import { ulid as ulid7 } from "ulid";
 
 // src/kernel/scheduler/fsrs.ts
 var DEFAULT_W = [
@@ -3550,7 +3707,7 @@ async function evaluateRatingWithinTransaction(db, input) {
     due_at: updated.dueAt.toISOString(),
     last_review_at: now.toISOString()
   });
-  const reviewLogId = input.reviewLogId ?? ulid6();
+  const reviewLogId = input.reviewLogId ?? ulid7();
   await db.prepare(
     `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
@@ -3884,7 +4041,7 @@ async function applySessionSynthesis(db, input) {
       return { applied: false, record: parseSynthesisRow(existing) };
     }
     const card = await ensureCard(tx, token.id, session.user_id);
-    const reviewLogId = ulid7();
+    const reviewLogId = ulid8();
     await evaluateRatingWithinTransaction(tx, {
       cardId: card.id,
       tokenId: token.id,
@@ -4713,8 +4870,7 @@ async function buildReviewQueue(db, options) {
   const maxReviews = options.maxReviews ?? 50;
   const now = options.now ?? /* @__PURE__ */ new Date();
   const nowISO = now.toISOString();
-  const dueRows = await db.prepare(
-    `SELECT
+  let dueSql = `SELECT
          c.id       AS card_id,
          c.token_id AS token_id,
          t.slug     AS slug,
@@ -4732,11 +4888,19 @@ async function buildReviewQueue(db, options) {
          AND c.blocked = 0
          AND c.due_at <= ?
          AND c.state IN ('review', 'relearning', 'learning')
-         AND t.deprecated_at IS NULL
-       ORDER BY c.due_at ASC`
-  ).all(options.userId, nowISO);
-  const newRows = await db.prepare(
-    `SELECT
+         AND t.deprecated_at IS NULL`;
+  const dueParams = [options.userId, nowISO];
+  if (options.knowledgeContext) {
+    dueSql += ` AND EXISTS (
+      SELECT 1 FROM token_contexts tc
+      INNER JOIN contexts ctx ON ctx.id = tc.context_id
+      WHERE tc.token_id = t.id AND ctx.name = ?
+    )`;
+    dueParams.push(options.knowledgeContext);
+  }
+  dueSql += ` ORDER BY c.due_at ASC`;
+  const dueRows = await db.prepare(dueSql).all(...dueParams);
+  let newSql = `SELECT
          c.id       AS card_id,
          c.token_id AS token_id,
          t.slug     AS slug,
@@ -4753,10 +4917,19 @@ async function buildReviewQueue(db, options) {
        WHERE c.user_id = ?
          AND c.blocked = 0
          AND c.state = 'new'
-         AND t.deprecated_at IS NULL
-       ORDER BY t.bloom_level ASC, t.slug ASC
-       LIMIT ?`
-  ).all(options.userId, maxNew);
+         AND t.deprecated_at IS NULL`;
+  const newParams = [options.userId];
+  if (options.knowledgeContext) {
+    newSql += ` AND EXISTS (
+      SELECT 1 FROM token_contexts tc
+      INNER JOIN contexts ctx ON ctx.id = tc.context_id
+      WHERE tc.token_id = t.id AND ctx.name = ?
+    )`;
+    newParams.push(options.knowledgeContext);
+  }
+  newSql += ` ORDER BY t.bloom_level ASC, t.slug ASC LIMIT ?`;
+  newParams.push(maxNew);
+  const newRows = await db.prepare(newSql).all(...newParams);
   const nowMs = now.getTime();
   const sortedDue = [...dueRows].sort((a, b) => {
     const overdueA = nowMs - new Date(a.due_at).getTime();
@@ -5503,6 +5676,27 @@ function detectSyncProvider(dir) {
   }
   return null;
 }
+function getActiveWorkspaceContext(path = defaultConfigPath()) {
+  const activeWorkspace = getActiveWorkspace(path);
+  return activeWorkspace?.activeKnowledgeContext;
+}
+function setActiveWorkspaceContext(contextName, path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  const activeId = config.activeWorkspaceId;
+  if (activeId && config.workspaces) {
+    const workspace = config.workspaces.find((w) => w.id === activeId);
+    if (workspace) {
+      if (contextName) {
+        workspace.activeKnowledgeContext = contextName;
+      } else {
+        delete workspace.activeKnowledgeContext;
+      }
+      saveInstallConfig(config, path);
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/kernel/system/installer.ts
 import { execFileSync, execSync } from "child_process";
@@ -5998,6 +6192,7 @@ export {
   analyzeObservation,
   appendUiObservationReport,
   applySessionSynthesis,
+  assignTokenToContext,
   buildAncestorMap,
   buildReviewQueue,
   buildUiSynthesisCandidates,
@@ -6015,12 +6210,14 @@ export {
   createAgentSkill,
   createFSRS,
   createGoal,
+  createKnowledgeContext,
   createToken,
   decidePostCapture,
   decidePreCapture,
   decideUpdate,
   decodeEmbedding,
   deleteCardForUser,
+  deleteKnowledgeContext,
   deleteSetting,
   deleteToken,
   deprecateToken,
@@ -6052,6 +6249,7 @@ export {
   generateZshUnhooks,
   getADOCredentials,
   getActiveWorkspace,
+  getActiveWorkspaceContext,
   getActiveWorkspaceId,
   getAgentSkill,
   getAllSettings,
@@ -6072,6 +6270,8 @@ export {
   getGoalTree,
   getInstallChannel,
   getInstallMode,
+  getKnowledgeContextById,
+  getKnowledgeContextByName,
   getMachineAiConfig,
   getMonitorDir,
   getMonitorLogStats,
@@ -6108,8 +6308,10 @@ export {
   isOllamaInstalled,
   isUiObservationReport,
   listAgentSkills,
+  listContextsForToken,
   listEmbeddedTokens,
   listGoals,
+  listKnowledgeContexts,
   listPersonalCards,
   listProviderApiKeyRefs,
   listTokens,
@@ -6156,6 +6358,7 @@ export {
   searchTokensHybrid,
   serializeGoal,
   setADOCredentials,
+  setActiveWorkspaceContext,
   setActiveWorkspaceId,
   setInstallChannel,
   setInstallMode,
@@ -6170,9 +6373,11 @@ export {
   toSidecarPrivacyPolicy,
   uiObservationLogExists,
   uiObservationTimeSpan,
+  unassignTokenFromContext,
   unblockReady,
   updateCard,
   updateGoalStatus,
+  updateKnowledgeContext,
   updateToken,
   upsertConfiguredWorkspace,
   upsertTokenEmbedding,