fuli-context 0.4.0 → 0.7.2

package/src/graphiti/agent-knowledge-workflows.js

@@ -2,9 +2,14 @@ import { createHash } from 'node:crypto';
 
 import { onlineSourceUri } from './source-uri.js';
 
-export async function beginTaskContext(application, { sessionId, projectPath }) {
+export async function beginTaskContext(application, {
+  sessionId,
+  projectPath,
+  taskPrompt = null
+}) {
   const preferences = await application.getCollaborationPreferences({
     projectPath,
+    taskPrompt,
     agentInvocation: true,
     agentToolName: 'begin_task_context'
   });
@@ -19,7 +24,7 @@ export async function beginTaskContext(application, { sessionId, projectPath })
     previous_checkpoint_missing: task.previousCheckpointMissing,
     ...preferences,
     task_guidance: {
-      retrieval: 'Use search_current_project_knowledge for project work; it resolves the current project and inherited parent knowledge without copying IDs.',
+      retrieval: 'Inspect task_knowledge_recall before asking for a stable project fact or method again. On a miss, use search_current_project_knowledge with focused action, artifact, target-system, or identifier queries; never use the full conversational request as the only query.',
       checkpoint: 'Before finishing, call checkpoint_task_knowledge with capture_candidates or retain_nothing.'
     }
   };

package/src/graphiti/federated-application.js

@@ -1,3 +1,5 @@
+import { dirname } from 'node:path';
+
 import { GraphitiProviderClient } from './provider-client.js';
 import {
   canonicalProviderUrl,
@@ -22,8 +24,15 @@ import {
   createFuliSourceMarker,
   sourceConsoleUrl
 } from './source-marker.js';
+import {
+  recallTaskKnowledge,
+  TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE
+} from './task-knowledge-recall.js';
 import { resolvePersonalProjectPath } from './project-path-context.js';
+import { mergeExternalKnowledgeProjection } from '../external-knowledge/graph-projection.js';
 import { TaskContextRegistry } from '../mcp/task-context-registry.js';
+import { attachExternalKnowledgeRuntime } from '../external-knowledge/runtime.js';
+import { resolveSetupPaths } from '../setup/paths.js';
 import {
   agentProjectResolution,
   beginTaskContext as beginTaskContextWorkflow,
@@ -40,19 +49,27 @@ import {
   providerConfirmationBasis,
   providerEpisode
 } from './knowledge-provider-mapping.js';
+import { providerProjectProfile } from './project-profile-mapping.js';
+import {
+  finishKnowledgeReview as finishKnowledgeReviewWorkflow,
+  listKnowledgeReviewCandidates as listKnowledgeReviewCandidatesWorkflow,
+  recordKnowledgeReviewProgress as recordKnowledgeReviewProgressWorkflow,
+  startKnowledgeReview as startKnowledgeReviewWorkflow
+} from './knowledge-review.js';
 
 export function openFederatedGraphApplication({
   runtimeConfigPath,
   config,
   capturePolicyStore,
   agentAccessPolicyStore,
-  fetchImpl = globalThis.fetch
+  fetchImpl = globalThis.fetch,
+  env = process.env
 }) {
   const resolved = config ?? readGraphRuntimeConfig(runtimeConfigPath);
   const policyStore = capturePolicyStore ?? new CapturePolicyStore(
     capturePolicyPathForRuntime(runtimeConfigPath)
   );
-  return new FederatedGraphApplication(resolved, {
+  const app = new FederatedGraphApplication(resolved, {
     fetchImpl,
     capturePolicyStore: policyStore,
     agentAccessPolicyStore: agentAccessPolicyStore ?? new AgentAccessPolicyStore(
@@ -60,6 +77,14 @@ export function openFederatedGraphApplication({
     ),
     consoleUrl: sourceConsoleUrl(runtimeConfigPath)
   });
+  if (typeof runtimeConfigPath === 'string' && runtimeConfigPath) {
+    attachExternalKnowledgeRuntime(app, {
+      paths: resolveSetupPaths({ dataDir: dirname(runtimeConfigPath) }),
+      env,
+      fetchImpl
+    });
+  }
+  return app;
 }
 
 export class FederatedGraphApplication {
@@ -163,6 +188,7 @@ export class FederatedGraphApplication {
   async getCollaborationPreferences({
     personalProjectId = null,
     projectPath = null,
+    taskPrompt = null,
     limit = 100,
     agentInvocation = false,
     agentToolName = 'get_collaboration_preferences'
@@ -188,6 +214,9 @@ export class FederatedGraphApplication {
       result,
       queuedConflicts
     );
+    const taskKnowledgeRecall = taskPrompt === null
+      ? null
+      : await recallTaskKnowledge(this, projectResolution, taskPrompt);
     if (agentInvocation) {
       const items = [
         ...(result.global_preferences ?? []),
@@ -207,14 +236,16 @@ export class FederatedGraphApplication {
       conflicts: 'Do not apply entries listed in conflicts until the user resolves them.',
       deferred_conflicts: 'If the current task would use a deferred_conflict, call resolve_deferred_preference_conflict before applying either side. Ignore unrelated deferred conflicts. The resolution must preserve the AI audit marker.',
       authority: 'Human or authoritative-source confirmed preferences outrank agent-confirmed preferences. Agent-confirmed preferences are usable but lower priority and remain explicitly marked.',
-      pending: 'Pending preferences are available only through on-demand knowledge search; invalid and unrelated-project preferences are excluded. Automatic preference injection never counts as usage evidence.'
+      pending: 'Pending preferences are available only through on-demand knowledge search; invalid and unrelated-project preferences are excluded. Automatic preference injection never counts as usage evidence.',
+      knowledge_retrieval: TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE
     };
     if (!agentInvocation) {
       return {
         ...result,
         deferred_conflicts: deferredConflicts,
         application_guidance: applicationGuidance,
-        project_resolution: agentProjectResolution(projectResolution)
+        project_resolution: agentProjectResolution(projectResolution),
+        ...(taskKnowledgeRecall ? { task_knowledge_recall: taskKnowledgeRecall } : {})
       };
     }
     return {
@@ -222,6 +253,7 @@ export class FederatedGraphApplication {
         .map(agentCollaborationPreference),
       deferred_conflicts: deferredConflicts.map(agentDeferredPreferenceConflict),
       application_guidance: applicationGuidance,
+      ...(taskKnowledgeRecall ? { task_knowledge_recall: taskKnowledgeRecall } : {}),
       context: {
         personal_space_id: result.personal_space_id,
         personal_project_id: result.personal_project_id,
@@ -293,7 +325,9 @@ export class FederatedGraphApplication {
     if (!['bounded', 'all_local_confirmed'].includes(personalProjectScope)) {
       throw new TypeError('Unknown personal project search scope');
     }
-    const subscriptions = await this.personal.listSubscriptions(personalSpaceId);
+    const subscriptions = projectIds.length
+      ? await this.personal.listSubscriptions(personalSpaceId)
+      : [];
     const requestedProjects = new Set(projectIds);
     const selectedSubscriptions = subscriptions.filter(({ project_id: projectId }) =>
       requestedProjects.has(projectId)
@@ -451,6 +485,7 @@ export class FederatedGraphApplication {
     providerUrl = null,
     personalProjectId = null,
     limit = 500,
+    offset = null,
     agentInvocation = false,
     agentToolName = 'get_knowledge_graph'
   }) {
@@ -458,19 +493,42 @@ export class FederatedGraphApplication {
       if (spaceId !== this.config.personal.spaceId) {
         throw new TypeError('A configured providerUrl is required for a team-shared project graph');
       }
-      const result = await this.personal.graph(spaceId, limit, personalProjectId);
+      const result = await this.personal.graph(
+        spaceId,
+        limit,
+        personalProjectId,
+        offset
+      );
       if (agentInvocation) {
         await this.#recordAgentViews([
           ...result.nodes.map(({ id }) => ({ item_id: id, item_kind: 'entity' })),
           ...result.edges.map(({ id }) => ({ item_id: id, item_kind: 'relationship' }))
         ], agentToolName);
       }
-      return result;
+      return mergeExternalKnowledgeProjection(
+        this.externalKnowledge, result, spaceId, personalProjectId
+      );
     }
     if (personalProjectId) {
       throw new TypeError('Personal project scope cannot be used with a team-shared provider');
     }
-    return this.#workspace(providerUrl).client.graph(spaceId, limit);
+    return this.#workspace(providerUrl).client.graph(spaceId, limit, null, offset);
+  }
+
+  async startKnowledgeReview(input) {
+    return startKnowledgeReviewWorkflow(this, input);
+  }
+
+  async listKnowledgeReviewCandidates(input) {
+    return listKnowledgeReviewCandidatesWorkflow(this, input);
+  }
+
+  async recordKnowledgeReviewProgress(input) {
+    return recordKnowledgeReviewProgressWorkflow(this, input);
+  }
+
+  async finishKnowledgeReview(input) {
+    return finishKnowledgeReviewWorkflow(this, input);
   }
 
   async recordKnowledgeUsage({
@@ -1203,39 +1261,6 @@ function assertSafeKnowledgeMutation(input) {
   }
 }
 
-function providerProjectProfile(profile) {
-  if (!profile || typeof profile !== 'object') throw new TypeError('Project profile is required');
-  const assessment = profile.assessment ? sanitizeProjectAssessment(profile.assessment) : null;
-  return {
-    name: profile.name,
-    purpose: profile.purpose ?? null,
-    scope: profile.scope ?? null,
-    technical_summary: profile.technical_summary ?? profile.technicalSummary ?? null,
-    lifecycle: profile.lifecycle ?? 'planned',
-    sources: profile.sources ?? [],
-    boundaries: profile.boundaries ?? [],
-    assessment
-  };
-}
-
-function sanitizeProjectAssessment(input) {
-  const assessment = {
-    score: input.score,
-    label: input.label,
-    confirmed: input.confirmed ?? [],
-    inferred: input.inferred ?? [],
-    dimensions: (input.dimensions ?? []).map((dimension) => ({
-      key: dimension.key,
-      label: dimension.label,
-      score: dimension.score,
-      state: dimension.state === 'missing' ? 'inferred' : dimension.state,
-      evidence: dimension.evidence ?? []
-    })),
-    analyzed_at: input.analyzed_at ?? input.analyzedAt
-  };
-  return assessment;
-}
-
 function groupSubscriptions(subscriptions) {
   const grouped = new Map();
   for (const subscription of subscriptions) {

package/src/graphiti/knowledge-item-role.js

@@ -0,0 +1,21 @@
+const SUPPORTING_ENTITY_TYPES = new Set([
+  'DecisionOption',
+  'DecisionRationale',
+  'ValidationResult'
+]);
+
+const SUPPORTING_RELATIONSHIPS = new Set([
+  'MOTIVATED_BY',
+  'REJECTED_OPTION',
+  'VALIDATED_BY'
+]);
+
+export function knowledgeItemRole(item) {
+  if (
+    SUPPORTING_ENTITY_TYPES.has(item?.type)
+    || SUPPORTING_RELATIONSHIPS.has(item?.relationship)
+  ) {
+    return 'supporting';
+  }
+  return 'primary';
+}

package/src/graphiti/knowledge-review.js

@@ -0,0 +1,43 @@
+export function startKnowledgeReview(app, input) {
+  assertActivePersonalSpace(app, input.personalSpaceId);
+  return app.personal.startKnowledgeReview({
+    personal_space_id: input.personalSpaceId,
+    scope: input.scope,
+    personal_project_id: input.personalProjectId ?? null
+  });
+}
+
+export function listKnowledgeReviewCandidates(app, input) {
+  assertActivePersonalSpace(app, input.personalSpaceId);
+  return app.personal.listKnowledgeReviewCandidates({
+    personal_space_id: input.personalSpaceId,
+    review_id: input.reviewId,
+    limit: input.limit
+  });
+}
+
+export function recordKnowledgeReviewProgress(app, input) {
+  assertActivePersonalSpace(app, input.personalSpaceId);
+  return app.personal.recordKnowledgeReviewProgress({
+    personal_space_id: input.personalSpaceId,
+    review_id: input.reviewId,
+    candidate_key: input.candidateKey,
+    outcome: input.outcome,
+    note: input.note ?? null
+  });
+}
+
+export function finishKnowledgeReview(app, input) {
+  assertActivePersonalSpace(app, input.personalSpaceId);
+  return app.personal.finishKnowledgeReview({
+    personal_space_id: input.personalSpaceId,
+    review_id: input.reviewId,
+    disposition: input.disposition
+  });
+}
+
+function assertActivePersonalSpace(app, personalSpaceId) {
+  if (personalSpaceId !== app.config.personal.spaceId) {
+    throw new TypeError('Knowledge review must use the active personal space');
+  }
+}

package/src/graphiti/project-profile-mapping.js

@@ -0,0 +1,32 @@
+export function providerProjectProfile(profile) {
+  if (!profile || typeof profile !== 'object') {
+    throw new TypeError('Project profile is required');
+  }
+  return {
+    name: profile.name,
+    purpose: profile.purpose ?? null,
+    scope: profile.scope ?? null,
+    technical_summary: profile.technical_summary ?? profile.technicalSummary ?? null,
+    lifecycle: profile.lifecycle ?? 'planned',
+    sources: profile.sources ?? [],
+    boundaries: profile.boundaries ?? [],
+    assessment: profile.assessment ? providerProjectAssessment(profile.assessment) : null
+  };
+}
+
+function providerProjectAssessment(input) {
+  return {
+    score: input.score,
+    label: input.label,
+    confirmed: input.confirmed ?? [],
+    inferred: input.inferred ?? [],
+    dimensions: (input.dimensions ?? []).map((dimension) => ({
+      key: dimension.key,
+      label: dimension.label,
+      score: dimension.score,
+      state: dimension.state === 'missing' ? 'inferred' : dimension.state,
+      evidence: dimension.evidence ?? []
+    })),
+    analyzed_at: input.analyzed_at ?? input.analyzedAt
+  };
+}

package/src/graphiti/provider-client.js

@@ -118,6 +118,26 @@ export class GraphitiProviderClient {
   commit(input) {
     return this.#request('/v1/knowledge/commits', { method: 'POST', body: input });
   }
+  startKnowledgeReview(input) {
+    return this.#request('/v1/knowledge/reviews/start', {
+      method: 'POST', body: input
+    });
+  }
+  listKnowledgeReviewCandidates(input) {
+    return this.#request('/v1/knowledge/reviews/candidates', {
+      method: 'POST', body: input
+    });
+  }
+  recordKnowledgeReviewProgress(input) {
+    return this.#request('/v1/knowledge/reviews/progress', {
+      method: 'POST', body: input
+    });
+  }
+  finishKnowledgeReview(input) {
+    return this.#request('/v1/knowledge/reviews/finish', {
+      method: 'POST', body: input
+    });
+  }
   reviseKnowledgeItem(itemId, input) {
     return this.#request(`/v1/knowledge/items/${encodeURIComponent(itemId)}`, {
       method: 'PATCH', body: input
@@ -240,9 +260,10 @@ export class GraphitiProviderClient {
     if (personalProjectId) query.set('personal_project_id', personalProjectId);
     return this.#request(`/v1/collaboration-preferences?${query}`);
   }
-  graph(spaceId, limit = 500, personalProjectId = null) {
+  graph(spaceId, limit = 500, personalProjectId = null, offset = null) {
     const query = new URLSearchParams({ limit: String(limit) });
     if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (offset !== null) query.set('offset', String(offset));
     return this.#request(`/v1/spaces/${encodeURIComponent(spaceId)}/graph?${query}`);
   }
 

package/src/graphiti/source-marker.js

@@ -2,8 +2,10 @@ import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
 import { DEFAULT_FULI_PORT } from '../defaults.js';
+import { knowledgeItemRole } from './knowledge-item-role.js';
 
 const MAX_CITATIONS = 1;
+const PROJECT_SCOPE_PRIORITY_BOOST = 1;
 const DEFAULT_CONSOLE_URL = `http://127.0.0.1:${DEFAULT_FULI_PORT}`;
 
 export function sourceConsoleUrl(runtimeConfigPath, {
@@ -22,12 +24,16 @@ export function sourceConsoleUrl(runtimeConfigPath, {
 export function createFuliSourceMarker({
   consoleUrl = DEFAULT_CONSOLE_URL,
   facts = [],
-  entities = []
+  entities = [],
+  projectScopePriority = 'balanced'
 } = {}) {
+  const comparePriority = projectScopePriority === 'strict'
+    ? compareStrictProjectCitationPriority
+    : compareCitationPriority;
   const citations = uniqueCitations([
     ...facts.map(factCitation),
     ...entities.map(entityCitation)
-  ].filter(Boolean));
+  ].filter(Boolean)).sort(comparePriority);
   const status = citations.length ? 'matched' : 'no_match';
   return {
     required: true,
@@ -45,6 +51,10 @@ function factCitation(fact) {
     spaceId: fact.spaceId ?? fact.space_id,
     itemKind: 'relationship',
     itemId: fact.id,
+    definedProjectId: fact.defined_project_id,
+    scopeDistance: fact.scope_distance,
+    score: fact.score,
+    role: knowledgeItemRole(fact),
     title: [fact.source_entity, fact.target_entity].filter(Boolean).join(' → ') ||
       fact.fact || '关系知识'
   });
@@ -56,21 +66,62 @@ function entityCitation(entity) {
     spaceId: entity.spaceId ?? entity.space_id,
     itemKind: 'entity',
     itemId: entity.id,
+    definedProjectId: entity.defined_project_id,
+    scopeDistance: entity.scope_distance,
+    score: entity.score,
+    role: knowledgeItemRole(entity),
     title: entity.name || entity.summary || '实体知识'
   });
 }
 
-function citation({ scope, spaceId, itemKind, itemId, title }) {
+function citation({
+  scope,
+  spaceId,
+  itemKind,
+  itemId,
+  definedProjectId,
+  scopeDistance,
+  score,
+  role,
+  title
+}) {
   if (!['personal', 'project'].includes(scope) || !spaceId || !itemId) return null;
   return {
     scope,
     spaceId: String(spaceId),
     itemKind,
     itemId: String(itemId),
+    projectScoped: Boolean(definedProjectId),
+    scopeDistance: Number(scopeDistance ?? 0),
+    score: Number(score ?? 0),
+    role,
     title: singleLine(title)
   };
 }
 
+function compareCitationPriority(left, right) {
+  return citationPriority(right) - citationPriority(left);
+}
+
+function compareStrictProjectCitationPriority(left, right) {
+  if (left.projectScoped !== right.projectScoped) {
+    return Number(right.projectScoped) - Number(left.projectScoped);
+  }
+  if (left.projectScoped && left.scopeDistance !== right.scopeDistance) {
+    return left.scopeDistance - right.scopeDistance;
+  }
+  if (left.role !== right.role) {
+    return left.role === 'primary' ? -1 : 1;
+  }
+  return compareCitationPriority(left, right);
+}
+
+function citationPriority(value) {
+  const projectBoost = value.projectScoped ? PROJECT_SCOPE_PRIORITY_BOOST : 0;
+  const distancePenalty = Math.min(Math.max(value.scopeDistance, 0), 8) * 0.15;
+  return value.score + projectBoost - distancePenalty;
+}
+
 function uniqueCitations(citations) {
   const seen = new Set();
   return citations.filter(({ scope, spaceId, itemKind, itemId }) => {