recallx 1.0.7 → 1.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jazpiper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -225,3 +225,7 @@ For launcher paths, environment variables, and editor-specific setup, see `docs/
 - `docs/mcp.md` for MCP bridge setup
 - `docs/workflows.md` for common usage flows
 - `docs/schema.md` for storage and data model details
+
+## License
+
+MIT. See `LICENSE`.

package/app/server/app.js

@@ -9,7 +9,7 @@ import { AppError } from "./errors.js";
 import { isShortLogLikeAgentNodeInput, maybeCreatePromotionCandidate, recomputeAutomaticGovernance, resolveGovernancePolicy, resolveNodeGovernance, resolveRelationStatus, shouldPromoteActivitySummary } from "./governance.js";
 import { refreshAutomaticInferredRelationsForNode, reindexAutomaticInferredRelations } from "./inferred-relations.js";
 import { appendCurrentTelemetryDetails, createObservabilityWriter, summarizePayloadShape } from "./observability.js";
-import { buildSemanticCandidateBonusMap, buildCandidateRelationBonusMap, buildContextBundle, buildNeighborhoodItems, buildTargetRelatedRetrievalItems, bundleAsMarkdown, computeRankCandidateScore, shouldUseSemanticCandidateAugmentation } from "./retrieval.js";
+import { buildSemanticCandidateBonusMap, buildCandidateRelationBonusMap, buildContextBundle, buildNeighborhoodItems, buildNeighborhoodItemsBatch, buildTargetRelatedRetrievalItems, bundleAsMarkdown, computeRankCandidateScore, selectSemanticCandidateIds, shouldUseSemanticCandidateAugmentation } from "./retrieval.js";
 import { buildProjectGraph } from "./project-graph.js";
 import { createId, isPathWithinRoot } from "./utils.js";
 const relationTypeSet = new Set(relationTypes);
@@ -1779,19 +1779,17 @@ export function createRecallXApp(params) {
         }, (span) => {
             const repository = currentRepository();
             const nodeId = readRequestParam(request.params.id);
-            const result = buildNeighborhoodItems(repository, nodeId, {
+            const neighborhoodOptions = {
                 relationTypes: types,
                 includeInferred,
                 maxInferred
-            });
+            };
+            const result = buildNeighborhoodItems(repository, nodeId, neighborhoodOptions);
             const expanded = depth === 2
                 ? (() => {
                     const seen = new Set(result.map((item) => `${item.edge.relationId}:${item.node.id}:1`));
-                    const secondHop = result.flatMap((item) => buildNeighborhoodItems(repository, item.node.id, {
-                        relationTypes: types,
-                        includeInferred,
-                        maxInferred
-                    })
+                    const secondHopByNodeId = buildNeighborhoodItemsBatch(repository, result.map((item) => item.node.id), neighborhoodOptions);
+                    const secondHop = result.flatMap((item) => (secondHopByNodeId.get(item.node.id) ?? [])
                         .filter((nested) => nested.node.id !== nodeId)
                         .map((nested) => ({
                         ...nested,
@@ -1814,7 +1812,8 @@ export function createRecallXApp(params) {
                 })()
                 : result;
             span.addDetails({
-                resultCount: expanded.length
+                resultCount: expanded.length,
+                firstHopCount: result.length
             });
             return expanded;
         });
@@ -2154,8 +2153,9 @@ export function createRecallXApp(params) {
             });
             const semanticAugmentation = repository.getSemanticAugmentationSettings();
             const semanticEnabled = shouldUseSemanticCandidateAugmentation(query, candidates);
+            const semanticCandidateIds = selectSemanticCandidateIds(query, candidates);
             const semanticBonuses = semanticEnabled
-                ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(query, candidateNodeIds), semanticAugmentation)
+                ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(query, semanticCandidateIds), semanticAugmentation)
                 : new Map();
             const result = candidates
                 .map((node) => {
@@ -2179,7 +2179,9 @@ export function createRecallXApp(params) {
                 .sort((left, right) => right.score - left.score);
             span.addDetails({
                 resultCount: result.length,
-                semanticUsed: semanticEnabled
+                semanticUsed: semanticEnabled,
+                semanticCandidateCount: candidates.length,
+                semanticRankedCandidateCount: semanticCandidateIds.length
             });
             return result;
         });

package/app/server/inferred-relations.js

@@ -14,6 +14,9 @@ function normalizeText(value) {
 function normalizeTags(tags) {
     return Array.from(new Set(tags.map((tag) => normalizeText(tag)).filter(Boolean)));
 }
+function normalizeTexts(values) {
+    return values.map(normalizeText).filter(Boolean);
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -33,6 +36,10 @@ function mentionsNode(haystacks, candidate) {
         : false;
     return { idMention, titleMention };
 }
+function hasCheapMention(normalizedHaystacks, candidate) {
+    const normalizedTitle = normalizeText(candidate.title);
+    return normalizedHaystacks.some((haystack) => haystack.includes(candidate.id.toLowerCase()) || (normalizedTitle.length >= 5 && haystack.includes(normalizedTitle)));
+}
 function sortPair(left, right) {
     return left.localeCompare(right) <= 0 ? [left, right] : [right, left];
 }
@@ -154,36 +161,42 @@ function collectGeneratedCandidates(repository, target, trigger) {
         projectIds: new Set(projectMembershipsByNodeId.get(target.id) ?? []),
         artifactKeys: artifactKeysByNodeId.get(target.id) ?? { exactPaths: [], baseNames: [] }
     };
+    const normalizedTargetTexts = normalizeTexts([target.title, target.body, target.summary]);
     const activityBodies = trigger === "activity-append" || trigger === "reindex"
         ? repository
             .listNodeActivities(target.id, MAX_ACTIVITY_BODIES)
             .map((activity) => activity.body ?? "")
             .filter(Boolean)
         : [];
+    const normalizedActivityBodies = activityBodies.map(normalizeText).filter(Boolean);
     return candidates.flatMap((candidate) => {
         const generated = [];
+        const candidateProjectIds = projectMembershipsByNodeId.get(candidate.id) ?? [];
+        const candidateArtifacts = artifactKeysByNodeId.get(candidate.id) ?? { exactPaths: [], baseNames: [] };
         const tagOverlapCandidate = buildTagOverlapCandidate(target, candidate, targetContext.normalizedTags);
         if (tagOverlapCandidate) {
             generated.push(tagOverlapCandidate);
         }
-        const bodyReferenceCandidate = buildBodyReferenceCandidate(target, candidate);
+        const projectMembershipCandidate = buildProjectMembershipCandidate(target, candidate, candidateProjectIds, targetContext.projectIds);
+        if (projectMembershipCandidate) {
+            generated.push(projectMembershipCandidate);
+        }
+        const sharedArtifactCandidate = buildSharedArtifactCandidate(target, candidate, candidateArtifacts, targetContext.artifactKeys);
+        if (sharedArtifactCandidate) {
+            generated.push(sharedArtifactCandidate);
+        }
+        const candidateTexts = normalizeTexts([candidate.title, candidate.body, candidate.summary]);
+        const shouldCheckBodyReference = hasCheapMention(normalizedTargetTexts, candidate) || hasCheapMention(candidateTexts, target);
+        const bodyReferenceCandidate = shouldCheckBodyReference ? buildBodyReferenceCandidate(target, candidate) : null;
         if (bodyReferenceCandidate) {
             generated.push(bodyReferenceCandidate);
         }
-        if (activityBodies.length) {
+        if (normalizedActivityBodies.length && hasCheapMention(normalizedActivityBodies, candidate)) {
             const activityReferenceCandidate = buildActivityReferenceCandidate(target, candidate, activityBodies);
             if (activityReferenceCandidate) {
                 generated.push(activityReferenceCandidate);
             }
         }
-        const projectMembershipCandidate = buildProjectMembershipCandidate(target, candidate, projectMembershipsByNodeId.get(candidate.id) ?? [], targetContext.projectIds);
-        if (projectMembershipCandidate) {
-            generated.push(projectMembershipCandidate);
-        }
-        const sharedArtifactCandidate = buildSharedArtifactCandidate(target, candidate, artifactKeysByNodeId.get(candidate.id) ?? { exactPaths: [], baseNames: [] }, targetContext.artifactKeys);
-        if (sharedArtifactCandidate) {
-            generated.push(sharedArtifactCandidate);
-        }
         return generated;
     });
 }

package/app/server/observability.js

@@ -1,6 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
+import { createInterface } from "node:readline";
 import { createId } from "./utils.js";
 const telemetryStorage = new AsyncLocalStorage();
 function nowIso() {
@@ -45,6 +47,10 @@ function roundDuration(value) {
 function dateStamp(value) {
     return value.slice(0, 10);
 }
+function telemetryLogDate(entry) {
+    const match = /^telemetry-(\d{4}-\d{2}-\d{2})\.ndjson$/.exec(entry);
+    return match ? match[1] : null;
+}
 function normalizeRetentionDays(value) {
     return Math.max(1, Math.trunc(value || 14));
 }
@@ -341,24 +347,41 @@ export class ObservabilityWriter {
         }
         const files = entries
             .filter((entry) => /^telemetry-\d{4}-\d{2}-\d{2}\.ndjson$/.test(entry))
+            .filter((entry) => {
+            const stamp = telemetryLogDate(entry);
+            return stamp !== null && stamp >= dateStamp(new Date(sinceMs).toISOString());
+        })
             .sort();
         const events = [];
         for (const file of files) {
             const filePath = path.join(logsDir, file);
-            const content = await readFile(filePath, "utf8").catch(() => "");
-            for (const line of content.split("\n")) {
-                const event = parseJsonLine(line);
-                if (!event) {
-                    continue;
-                }
-                const eventMs = Date.parse(event.ts);
-                if (!Number.isFinite(eventMs) || eventMs < sinceMs) {
-                    continue;
-                }
-                if (options.surface && options.surface !== "all" && event.surface !== options.surface) {
-                    continue;
+            const stream = createReadStream(filePath, { encoding: "utf8" });
+            const lines = createInterface({
+                input: stream,
+                crlfDelay: Number.POSITIVE_INFINITY
+            });
+            try {
+                for await (const line of lines) {
+                    const event = parseJsonLine(line);
+                    if (!event) {
+                        continue;
+                    }
+                    const eventMs = Date.parse(event.ts);
+                    if (!Number.isFinite(eventMs) || eventMs < sinceMs) {
+                        continue;
+                    }
+                    if (options.surface && options.surface !== "all" && event.surface !== options.surface) {
+                        continue;
+                    }
+                    events.push(event);
                 }
-                events.push(event);
+            }
+            catch {
+                // Ignore individual file read failures so observability endpoints stay resilient.
+            }
+            finally {
+                lines.close();
+                stream.destroy();
             }
         }
         return {

package/app/server/retrieval.js

@@ -18,6 +18,7 @@ const boostedRelationRankWeights = {
 };
 const semanticCandidateMinSimilarity = 0.2;
 const semanticCandidateMaxBonus = 18;
+const maxSemanticPrefilterCandidates = 256;
 function resolveSemanticAugmentationSettings(settings) {
     return {
         minSimilarity: typeof settings?.minSimilarity === "number" && Number.isFinite(settings.minSimilarity)
@@ -38,7 +39,15 @@ function prioritizeItems(items, preset, maxItems, bonuses) {
         .map(({ item }) => item);
     return weighted.slice(0, maxItems);
 }
-function buildNeighborhoodResult(repository, nodeId, options) {
+function normalizeRetrievalText(value) {
+    return (value ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function tokenizeRetrievalText(value) {
+    return normalizeRetrievalText(value)
+        .split(/[^a-z0-9]+/g)
+        .filter((token) => token.length >= 3);
+}
+function listNeighborhoodCandidates(repository, nodeId, options) {
     const canonicalItems = repository.listRelatedNodes(nodeId, 1, options?.relationTypes).map(({ node, relation }) => ({
         node,
         edge: {
@@ -94,6 +103,13 @@ function buildNeighborhoodResult(repository, nodeId, options) {
             });
         })()
         : [];
+    return {
+        canonicalItems,
+        inferredItems
+    };
+}
+function buildNeighborhoodResult(repository, nodeId, options) {
+    const { canonicalItems, inferredItems } = listNeighborhoodCandidates(repository, nodeId, options);
     const usageSummaries = repository.getRelationUsageSummaries([...canonicalItems, ...inferredItems].map((item) => item.edge.relationId));
     const rankedCanonical = rankNeighborhoodItems(canonicalItems, usageSummaries, neighborhoodRetrievalRankWeights);
     const rankedInferred = options?.includeInferred && options.maxInferred
@@ -104,6 +120,27 @@ function buildNeighborhoodResult(repository, nodeId, options) {
         usageSummaries
     };
 }
+export function buildNeighborhoodItemsBatch(repository, nodeIds, options) {
+    const uniqueNodeIds = Array.from(new Set(nodeIds.filter(Boolean)));
+    const rawByNodeId = new Map();
+    const relationIds = [];
+    for (const nodeId of uniqueNodeIds) {
+        const raw = listNeighborhoodCandidates(repository, nodeId, options);
+        rawByNodeId.set(nodeId, raw);
+        relationIds.push(...raw.canonicalItems.map((item) => item.edge.relationId));
+        relationIds.push(...raw.inferredItems.map((item) => item.edge.relationId));
+    }
+    const usageSummaries = repository.getRelationUsageSummaries(relationIds);
+    const results = new Map();
+    for (const [nodeId, raw] of rawByNodeId.entries()) {
+        const rankedCanonical = rankNeighborhoodItems(raw.canonicalItems, usageSummaries, neighborhoodRetrievalRankWeights);
+        const rankedInferred = options?.includeInferred && options.maxInferred
+            ? rankNeighborhoodItems(raw.inferredItems, usageSummaries, neighborhoodRetrievalRankWeights, options.maxInferred)
+            : [];
+        results.set(nodeId, [...rankedCanonical, ...rankedInferred]);
+    }
+    return results;
+}
 function matchesSearchResultFilters(item, filters) {
     const typeMatches = !filters.types?.length || filters.types.includes(item.type);
     const statusMatches = !filters.status?.length || filters.status.includes(item.status);
@@ -214,6 +251,45 @@ export function buildSemanticCandidateBonusMap(semanticMatches, settings) {
         ];
     }));
 }
+function scoreSemanticPrefilterCandidate(normalizedQuery, queryTokens, candidate) {
+    const normalizedTitle = normalizeRetrievalText(candidate.title);
+    const normalizedSummary = normalizeRetrievalText(candidate.summary);
+    let score = 0;
+    if (normalizedTitle.includes(normalizedQuery)) {
+        score += 12;
+    }
+    if (normalizedSummary.includes(normalizedQuery)) {
+        score += 6;
+    }
+    for (const token of queryTokens) {
+        if (normalizedTitle.includes(token)) {
+            score += 2;
+        }
+        if (normalizedSummary.includes(token)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+export function selectSemanticCandidateIds(query, candidates, maxCandidates = maxSemanticPrefilterCandidates) {
+    if (candidates.length <= maxCandidates) {
+        return candidates.map((candidate) => candidate.id);
+    }
+    const normalizedQuery = normalizeRetrievalText(query);
+    if (!normalizedQuery) {
+        return candidates.slice(0, maxCandidates).map((candidate) => candidate.id);
+    }
+    const queryTokens = Array.from(new Set(tokenizeRetrievalText(query)));
+    return candidates
+        .map((candidate) => ({
+        id: candidate.id,
+        score: scoreSemanticPrefilterCandidate(normalizedQuery, queryTokens, candidate),
+        updatedAt: candidate.updatedAt
+    }))
+        .sort((left, right) => right.score - left.score || right.updatedAt.localeCompare(left.updatedAt))
+        .slice(0, maxCandidates)
+        .map((candidate) => candidate.id);
+}
 function computeBundleRelationBoost(item, summary) {
     return computeRelationRetrievalRank(item.edge, summary, {
         canonicalBase: 120,
@@ -397,15 +473,19 @@ export async function buildContextBundle(repository, input) {
     const candidateItems = [targetItem, ...relatedItems, ...decisions, ...openQuestions];
     const dedupedItems = Array.from(new Map(candidateItems.map((item) => [item.id, item])).values());
     const semanticQuery = [target.title, target.summary ?? target.body].filter(Boolean).join("\n");
-    const semanticBonuses = shouldUseSemanticCandidateAugmentation(semanticQuery, dedupedItems.filter((item) => item.id !== target.id))
-        ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(semanticQuery, dedupedItems.filter((item) => item.id !== target.id).map((item) => item.id)), repository.getSemanticAugmentationSettings())
+    const semanticCandidates = dedupedItems.filter((item) => item.id !== target.id);
+    const semanticCandidateIds = selectSemanticCandidateIds(semanticQuery, semanticCandidates);
+    const semanticBonuses = shouldUseSemanticCandidateAugmentation(semanticQuery, semanticCandidates)
+        ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(semanticQuery, semanticCandidateIds), repository.getSemanticAugmentationSettings())
         : new Map();
     appendCurrentTelemetryDetails({
         neighborhoodCount: neighborhood.length,
         relatedCandidateCount: relatedItems.length,
         decisionCount: decisions.length,
         openQuestionCount: openQuestions.length,
-        semanticUsed: semanticBonuses.size > 0
+        semanticUsed: semanticBonuses.size > 0,
+        semanticCandidateCount: semanticCandidates.length,
+        semanticRankedCandidateCount: semanticCandidateIds.length
     });
     const combinedBonuses = new Map();
     for (const item of dedupedItems) {

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.0.7";
+export const RECALLX_VERSION = "1.0.8";