byterover-cli 1.7.2 → 2.0.0

package/dist/server/core/domain/knowledge/memory-scoring.js

@@ -0,0 +1,217 @@
+/**
+ * FinMem-inspired memory scoring engine for knowledge lifecycle management.
+ *
+ * Provides pure functions for:
+ * - Compound scoring (BM25 relevance + importance + recency)
+ * - Exponential decay of importance and recency over time
+ * - Maturity tier determination with hysteresis (draft -> validated -> core)
+ * - Feedback recording (search access hits, curate updates)
+ *
+ * All functions are stateless and side-effect free.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Days for recency half-life (~21 days to halve) */
+export const DECAY_RECENCY_FACTOR = 30;
+/** Per-day importance multiplier (~78% after 50 days of non-use) */
+export const DECAY_IMPORTANCE_FACTOR = 0.995;
+/** Importance bonus per search hit */
+export const ACCESS_IMPORTANCE_BONUS = 3;
+/** Importance bonus per curate update */
+export const UPDATE_IMPORTANCE_BONUS = 5;
+/** BM25 relevance weight in compound score */
+export const W_RELEVANCE = 1.0;
+/** Importance weight in compound score */
+export const W_IMPORTANCE = 0;
+/** Recency weight in compound score */
+export const W_RECENCY = 0;
+/** Importance threshold to promote draft -> validated */
+export const PROMOTE_TO_VALIDATED = 65;
+/** Importance threshold to promote validated -> core */
+export const PROMOTE_TO_CORE = 85;
+/** Importance threshold to demote core -> validated (hysteresis gap) */
+export const DEMOTE_FROM_CORE = 60;
+/** Importance threshold to demote validated -> draft (hysteresis gap) */
+export const DEMOTE_FROM_VALIDATED = 35;
+/** Search score multiplier per maturity tier */
+export const TIER_BOOST = {
+    core: 1,
+    draft: 1,
+    validated: 1,
+};
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+/**
+ * Compute compound score for retrieval ranking.
+ *
+ * Combines BM25 text relevance with importance and recency signals,
+ * then applies a tier-based boost.
+ *
+ * @param bm25Normalized - Normalized BM25 score in [0, 1)
+ * @param importance - Importance score in [0, 100]
+ * @param recency - Recency score in [0, 1]
+ * @param maturity - Maturity tier ('draft' | 'validated' | 'core')
+ * @returns Compound score (typically in [0, ~1.15])
+ */
+export function compoundScore(bm25Normalized, importance, recency, maturity) {
+    const normalizedImportance = Math.min(importance, 100) / 100;
+    const base = W_RELEVANCE * bm25Normalized + W_IMPORTANCE * normalizedImportance + W_RECENCY * recency;
+    const boost = TIER_BOOST[maturity] ?? TIER_BOOST.draft;
+    return base * boost;
+}
+/**
+ * Apply time-based exponential decay to scoring fields.
+ *
+ * Recency decays as exp(-days / DECAY_RECENCY_FACTOR).
+ * Importance decays as importance * DECAY_IMPORTANCE_FACTOR^days.
+ *
+ * @param scoring - Current scoring state
+ * @param daysSinceLastUpdate - Days since the file was last updated
+ * @returns New scoring with decayed values (original not mutated)
+ */
+export function applyDecay(scoring, daysSinceLastUpdate) {
+    if (daysSinceLastUpdate <= 0) {
+        return scoring;
+    }
+    const currentImportance = scoring.importance ?? 50;
+    const newRecency = Math.exp(-daysSinceLastUpdate / DECAY_RECENCY_FACTOR);
+    const newImportance = currentImportance * DECAY_IMPORTANCE_FACTOR ** daysSinceLastUpdate;
+    return {
+        ...scoring,
+        importance: Math.max(0, newImportance),
+        recency: newRecency,
+    };
+}
+/**
+ * Determine the maturity tier based on importance score.
+ *
+ * Uses hysteresis to prevent rapid oscillation between tiers:
+ * - Promote draft -> validated at importance >= 65
+ * - Promote validated -> core at importance >= 85
+ * - Demote core -> validated at importance < 60
+ * - Demote validated -> draft at importance < 35
+ *
+ * @param importance - Current importance score
+ * @param currentTier - Current maturity tier
+ * @returns The determined tier
+ */
+export function determineTier(importance, currentTier) {
+    // Promotion
+    if (importance >= PROMOTE_TO_CORE) {
+        return 'core';
+    }
+    if (importance >= PROMOTE_TO_VALIDATED && currentTier === 'draft') {
+        return 'validated';
+    }
+    // Demotion (with hysteresis gap)
+    if (currentTier === 'core' && importance < DEMOTE_FROM_CORE) {
+        return 'validated';
+    }
+    if (currentTier === 'validated' && importance < DEMOTE_FROM_VALIDATED) {
+        return 'draft';
+    }
+    return currentTier;
+}
+/**
+ * Record a search access hit on a knowledge file.
+ *
+ * Increments access count and adds an importance bonus.
+ *
+ * @param scoring - Current scoring state
+ * @returns Updated scoring (original not mutated)
+ */
+export function recordAccessHit(scoring) {
+    const newAccessCount = (scoring.accessCount ?? 0) + 1;
+    const newImportance = Math.min(100, (scoring.importance ?? 50) + ACCESS_IMPORTANCE_BONUS);
+    return {
+        ...scoring,
+        accessCount: newAccessCount,
+        importance: newImportance,
+    };
+}
+/**
+ * Record multiple accumulated access hits at once.
+ *
+ * @param scoring - Current scoring state
+ * @param hitCount - Number of hits to record
+ * @returns Updated scoring (original not mutated)
+ */
+export function recordAccessHits(scoring, hitCount) {
+    if (hitCount <= 0) {
+        return scoring;
+    }
+    const newAccessCount = (scoring.accessCount ?? 0) + hitCount;
+    const newImportance = Math.min(100, (scoring.importance ?? 50) + ACCESS_IMPORTANCE_BONUS * hitCount);
+    return {
+        ...scoring,
+        accessCount: newAccessCount,
+        importance: newImportance,
+    };
+}
+/**
+ * Record a curate update on a knowledge file.
+ *
+ * Increments update count, adds an importance bonus, resets recency to 1.0,
+ * and updates the timestamp.
+ *
+ * @param scoring - Current scoring state
+ * @returns Updated scoring (original not mutated)
+ */
+export function recordCurateUpdate(scoring) {
+    const newUpdateCount = (scoring.updateCount ?? 0) + 1;
+    const newImportance = Math.min(100, (scoring.importance ?? 50) + UPDATE_IMPORTANCE_BONUS);
+    const now = new Date().toISOString();
+    return {
+        ...scoring,
+        importance: newImportance,
+        recency: 1,
+        updateCount: newUpdateCount,
+        updatedAt: now,
+    };
+}
+/**
+ * Return default scoring values for a new or unscored knowledge file.
+ */
+export function applyDefaultScoring() {
+    const now = new Date().toISOString();
+    return {
+        accessCount: 0,
+        createdAt: now,
+        importance: 50,
+        maturity: 'draft',
+        recency: 1,
+        updateCount: 0,
+        updatedAt: now,
+    };
+}
+/**
+ * Merge two scoring states during a MERGE operation.
+ *
+ * Strategy:
+ * - importance: max of both
+ * - recency: max of both
+ * - accessCount: sum
+ * - updateCount: sum + 1 (for the merge itself)
+ * - maturity: higher tier
+ * - createdAt: earlier date
+ * - updatedAt: current time
+ */
+export function mergeScoring(source, target) {
+    const tierRank = { core: 3, draft: 1, validated: 2 };
+    const sourceRank = tierRank[source.maturity ?? 'draft'] ?? 1;
+    const targetRank = tierRank[target.maturity ?? 'draft'] ?? 1;
+    const higherTier = sourceRank >= targetRank ? (source.maturity ?? 'draft') : (target.maturity ?? 'draft');
+    const sourceCreated = source.createdAt ? new Date(source.createdAt).getTime() : Date.now();
+    const targetCreated = target.createdAt ? new Date(target.createdAt).getTime() : Date.now();
+    return {
+        accessCount: (source.accessCount ?? 0) + (target.accessCount ?? 0),
+        createdAt: sourceCreated <= targetCreated ? source.createdAt : target.createdAt,
+        importance: Math.max(source.importance ?? 50, target.importance ?? 50),
+        maturity: higherTier,
+        recency: Math.max(source.recency ?? 1, target.recency ?? 1),
+        updateCount: (source.updateCount ?? 0) + (target.updateCount ?? 0) + 1,
+        updatedAt: new Date().toISOString(),
+    };
+}

package/dist/server/core/domain/knowledge/relation-parser.d.ts

@@ -72,9 +72,25 @@ export declare function formatRelation(domain: string, topic: string, title: str
  * ```
  */
 export declare function normalizeRelation(relation: string): string;
+/**
+ * Normalize a relation path: remove @ prefix, ensure .md extension,
+ * lowercase, and replace spaces with underscores.
+ *
+ * @param relation - Relation path (with or without @ prefix)
+ * @returns Normalized relation path
+ *
+ * @example
+ * ```ts
+ * normalizeRelationPath('Architecture/Agents/Overview.md') // 'architecture/agents/overview.md'
+ * normalizeRelationPath('@code_style/error-handling/overview') // 'code_style/error-handling/overview.md'
+ * normalizeRelationPath('Architecture/Agents/Sandbox and Security.md') // 'architecture/agents/sandbox_and_security.md'
+ * ```
+ */
+export declare function normalizeRelationPath(relation: string): string;
 /**
  * Generate the Relations section for context.md.
  * Returns empty string if no relations provided.
+ * @deprecated Use frontmatter `related` field instead. Kept for backward compatibility.
  *
  * @param relations - Array of relation paths (with or without @ prefix)
  * @returns Markdown formatted Relations section or empty string

package/dist/server/core/domain/knowledge/relation-parser.js

@@ -94,9 +94,29 @@ export function formatRelation(domain, topic, title, subtopic) {
 export function normalizeRelation(relation) {
     return relation.replace(/^@+/, '');
 }
+/**
+ * Normalize a relation path: remove @ prefix, ensure .md extension,
+ * lowercase, and replace spaces with underscores.
+ *
+ * @param relation - Relation path (with or without @ prefix)
+ * @returns Normalized relation path
+ *
+ * @example
+ * ```ts
+ * normalizeRelationPath('Architecture/Agents/Overview.md') // 'architecture/agents/overview.md'
+ * normalizeRelationPath('@code_style/error-handling/overview') // 'code_style/error-handling/overview.md'
+ * normalizeRelationPath('Architecture/Agents/Sandbox and Security.md') // 'architecture/agents/sandbox_and_security.md'
+ * ```
+ */
+export function normalizeRelationPath(relation) {
+    const normalized = normalizeRelation(relation);
+    const withExtension = normalized.endsWith('.md') ? normalized : `${normalized}.md`;
+    return withExtension.toLowerCase().replaceAll(/\s+/g, '_');
+}
 /**
  * Generate the Relations section for context.md.
  * Returns empty string if no relations provided.
+ * @deprecated Use frontmatter `related` field instead. Kept for backward compatibility.
  *
  * @param relations - Array of relation paths (with or without @ prefix)
  * @returns Markdown formatted Relations section or empty string
@@ -118,14 +138,7 @@ export function generateRelationsSection(relations) {
         return '';
     }
     const formattedRelations = relations
-        .map(rel => {
-        const normalized = normalizeRelation(rel);
-        // Ensure .md extension is present
-        const withExtension = normalized.endsWith('.md') ? normalized : `${normalized}.md`;
-        // Normalize: lowercase and replace spaces with underscores
-        const normalizedPath = withExtension.toLowerCase().replaceAll(/\s+/g, '_');
-        return `@${normalizedPath}`;
-    })
+        .map(rel => `@${normalizeRelationPath(rel)}`)
         .join('\n');
     return `\n## Relations\n${formattedRelations}\n`;
 }

package/dist/server/core/domain/project/project-info.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ProjectInfo entity — maps a project to its XDG storage location.
+ *
+ * Each registered project has a unique sanitized directory name under
+ * <global-data-dir>/projects/ where runtime data (sessions, SQLite DBs)
+ * is stored.
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for ProjectInfo validation and serialization.
+ */
+export declare const ProjectInfoSchema: z.ZodObject<{
+    projectPath: z.ZodEffects<z.ZodString, string, string>;
+    registeredAt: z.ZodNumber;
+    sanitizedPath: z.ZodEffects<z.ZodString, string, string>;
+    storagePath: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    storagePath: string;
+    projectPath: string;
+    registeredAt: number;
+    sanitizedPath: string;
+}, {
+    storagePath: string;
+    projectPath: string;
+    registeredAt: number;
+    sanitizedPath: string;
+}>;
+/**
+ * Serialized form of ProjectInfo for persistence in registry.json.
+ */
+export type ProjectInfoJson = z.infer<typeof ProjectInfoSchema>;
+/**
+ * Type guard for validating parsed JSON as ProjectInfoJson.
+ */
+export declare function isValidProjectInfoJson(value: unknown): value is ProjectInfoJson;
+/**
+ * Represents a registered project and its XDG storage mapping.
+ */
+export declare class ProjectInfo {
+    readonly projectPath: string;
+    readonly registeredAt: number;
+    readonly sanitizedPath: string;
+    readonly storagePath: string;
+    constructor(params: ProjectInfoJson);
+    /**
+     * Deserializes a ProjectInfo from its JSON representation.
+     * Returns undefined if the JSON fails validation.
+     */
+    static fromJson(json: ProjectInfoJson): ProjectInfo | undefined;
+    /**
+     * Serializes the ProjectInfo to JSON format for persistence.
+     */
+    toJson(): ProjectInfoJson;
+}

package/dist/server/core/domain/project/project-info.js

@@ -0,0 +1,62 @@
+/**
+ * ProjectInfo entity — maps a project to its XDG storage location.
+ *
+ * Each registered project has a unique sanitized directory name under
+ * <global-data-dir>/projects/ where runtime data (sessions, SQLite DBs)
+ * is stored.
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for ProjectInfo validation and serialization.
+ */
+export const ProjectInfoSchema = z.object({
+    projectPath: z.string().refine((s) => s.trim().length > 0, { message: 'ProjectInfo projectPath cannot be empty' }),
+    registeredAt: z.number().positive({ message: 'ProjectInfo registeredAt must be a positive number' }),
+    sanitizedPath: z.string().refine((s) => s.trim().length > 0, { message: 'ProjectInfo sanitizedPath cannot be empty' }),
+    storagePath: z.string().refine((s) => s.trim().length > 0, { message: 'ProjectInfo storagePath cannot be empty' }),
+});
+/**
+ * Type guard for validating parsed JSON as ProjectInfoJson.
+ */
+export function isValidProjectInfoJson(value) {
+    return ProjectInfoSchema.safeParse(value).success;
+}
+/**
+ * Represents a registered project and its XDG storage mapping.
+ */
+export class ProjectInfo {
+    projectPath;
+    registeredAt;
+    sanitizedPath;
+    storagePath;
+    constructor(params) {
+        const parsed = ProjectInfoSchema.parse(params);
+        this.projectPath = parsed.projectPath;
+        this.sanitizedPath = parsed.sanitizedPath;
+        this.storagePath = parsed.storagePath;
+        this.registeredAt = parsed.registeredAt;
+    }
+    /**
+     * Deserializes a ProjectInfo from its JSON representation.
+     * Returns undefined if the JSON fails validation.
+     */
+    static fromJson(json) {
+        try {
+            return new ProjectInfo(json);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Serializes the ProjectInfo to JSON format for persistence.
+     */
+    toJson() {
+        return {
+            projectPath: this.projectPath,
+            registeredAt: this.registeredAt,
+            sanitizedPath: this.sanitizedPath,
+            storagePath: this.storagePath,
+        };
+    }
+}