archgraph-argo 0.10.31 → 0.10.33

package/argo/scripts/argo-mcp-server.js

@@ -66,6 +66,7 @@ const SYSTEM_ARCHITECTURE_TOOL_NAMES = new Set([
   'removeArchitectureView',
   'generateArchitectureDiffPlantuml',
   'queryNeo4jGraph',
+  'memory_search',
 ]);
 
 const TOOLS = [

package/argo/scripts/graph-rag/defaultSemanticRetrieval.js

@@ -36,7 +36,7 @@ const APPROVED_PROFILE = Object.freeze({
   model: 'qwen3.7-text-embedding',
   provider: 'alibaba-cloud-model-studio-openai-compatible-cn-beijing',
   version: 'qualification-2026-07-25',
-  dimensions: 1024,
+  dimensions: 1536,
 });
 const CHANNELS = Object.freeze([
   Object.freeze({
@@ -80,7 +80,37 @@ const READINESS_QUERY_CYPHER = [
   'RETURN properties(readiness) AS readiness',
 ].join('\n');
 const INITIAL_WINDOW_SIZE = 2;
+// Purpose-aware, env-configurable similarity thresholds + bounded top-K recall.
+// Audit keeps the strict threshold (precision); memory-retrieval purposes use a
+// looser threshold so relevant-but-paraphrased memory is recalled, while results
+// are bounded to ARGO_SEMANTIC_TOP_K so noise stays bounded. Thresholds are
+// overridable per channel via ARGO_SEMANTIC_{MEMORY|AUDIT}_THRESHOLD_<CHANNEL>.
+const AUDIT_PURPOSES = new Set(['audit']);
+const DEFAULT_MEMORY_THRESHOLD = 0.55;
+const DEFAULT_AUDIT_THRESHOLD = 0.8;
+const DEFAULT_TOP_K = 8;
 const SELECTED_VIEW_ID = 'semprod-wp2-default-retrieval-readiness';
+
+function envNumber(key, fallback) {
+  const value = Number(process.env[key]);
+  return Number.isFinite(value) ? value : fallback;
+}
+function memoryThresholdFor(channel) {
+  return envNumber(
+    `ARGO_SEMANTIC_MEMORY_THRESHOLD_${channel.channel.toUpperCase()}`,
+    envNumber('ARGO_SEMANTIC_MEMORY_THRESHOLD', DEFAULT_MEMORY_THRESHOLD),
+  );
+}
+function auditThresholdFor(channel) {
+  return envNumber(
+    `ARGO_SEMANTIC_AUDIT_THRESHOLD_${channel.channel.toUpperCase()}`,
+    envNumber('ARGO_SEMANTIC_AUDIT_THRESHOLD', DEFAULT_AUDIT_THRESHOLD),
+  );
+}
+function resolveTopK() {
+  const k = envNumber('ARGO_SEMANTIC_TOP_K', DEFAULT_TOP_K);
+  return Number.isInteger(k) && k > 0 ? k : DEFAULT_TOP_K;
+}
 const testCompositionStorage = new AsyncLocalStorage();
 
 function createDefaultSemanticRetrieval(dependencies = {}) {
@@ -173,12 +203,17 @@ async function executeWpP2Retrieval({
   });
   const vector = await provider.embed(request.intent);
   requireQualifiedVector(vector);
+  const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
+  const strict = AUDIT_PURPOSES.has(purpose);
+  const topK = resolveTopK();
   const seedsByType = {};
   for (const channel of CHANNELS) {
     seedsByType[channel.key] = await exhaustChannel({
       channel,
       neo4jDriver: composition.neo4jDriver,
       vector,
+      threshold: strict ? auditThresholdFor(channel) : memoryThresholdFor(channel),
+      maxSeeds: topK,
       ...(Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0
         ? { canonicalIdentities }
         : {}),
@@ -620,12 +655,24 @@ function publicReadinessOutcome(alignment) {
   };
 }
 
-async function exhaustChannel({ channel, neo4jDriver, vector, canonicalIdentities }) {
+async function exhaustChannel({
+  channel,
+  neo4jDriver,
+  vector,
+  canonicalIdentities,
+  threshold,
+  maxSeeds,
+}) {
   const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
+  const scopedCanonicalIdentities = scoped
+    ? scopeCanonicalIdentitiesForChannel(canonicalIdentities, channel)
+    : canonicalIdentities;
   const accepted = [];
   const seen = new Set();
+  const effectiveThreshold = typeof threshold === 'number' ? threshold : channel.threshold;
+  const effectiveMax = Number.isInteger(maxSeeds) && maxSeeds > 0 ? maxSeeds : Number.POSITIVE_INFINITY;
   let offset = 0;
-  while (true) {
+  while (accepted.length < effectiveMax) {
     const parameters = Object.freeze({
       indexName: channel.indexName,
       channel: channel.channel,
@@ -633,7 +680,7 @@ async function exhaustChannel({ channel, neo4jDriver, vector, canonicalIdentitie
       windowSize: INITIAL_WINDOW_SIZE,
       topK: offset + INITIAL_WINDOW_SIZE,
       vector,
-      ...(scoped ? { canonicalIdentities } : {}),
+      ...(scoped ? { canonicalIdentities: scopedCanonicalIdentities } : {}),
     });
     const result = await neo4jDriver.execute(Object.freeze({
       kind: 'semantic-vector-window-query',
@@ -645,8 +692,9 @@ async function exhaustChannel({ channel, neo4jDriver, vector, canonicalIdentitie
     const records = Array.isArray(result && result.records) ? result.records : [];
     const newlyVisible = records.slice(offset);
     for (const raw of newlyVisible) {
+      if (accepted.length >= effectiveMax) break;
       const record = normalizeVectorRecord(raw, channel);
-      if (record && record.score >= channel.threshold && !seen.has(record.id)) {
+      if (record && record.score >= effectiveThreshold && !seen.has(record.id)) {
         seen.add(record.id);
         accepted.push(Object.freeze(record));
       }
@@ -661,6 +709,22 @@ async function exhaustChannel({ channel, neo4jDriver, vector, canonicalIdentitie
   return Object.freeze(accepted);
 }
 
+// Scope identities come from the canonical graph as BARE ids (e.g.
+// "memory-eval-bench-wp-001"), but the semantic vector records store their
+// canonicalIdentity with a channel prefix (e.g. "Element:memory-eval-bench-wp-001").
+// Normalise the scope to the channel-prefixed form so the scoped Cypher
+// `node.canonicalIdentity IN $canonicalIdentities` actually matches. A bare id
+// that already carries a prefix (this or another channel's) is left as-is: it
+// simply won't match records of this channel, which is the correct no-op.
+function scopeCanonicalIdentitiesForChannel(identities, channel) {
+  if (!Array.isArray(identities)) return identities;
+  const prefix = `${channel.objectType}:`;
+  return identities.map(id => {
+    const text = String(id);
+    return text.includes(':') ? text : `${prefix}${text}`;
+  });
+}
+
 function normalizeVectorRecord(raw, channel) {
   if (!raw || typeof raw !== 'object') return undefined;
   const id = raw.canonicalIdentity || raw.id || raw.objectId;
@@ -979,4 +1043,9 @@ function safeError(category) {
 module.exports = {
   createDefaultSemanticRetrieval,
   withDefaultSemanticRetrievalTestComposition,
+  memoryThresholdFor,
+  auditThresholdFor,
+  resolveTopK,
+  scopeCanonicalIdentitiesForChannel,
+  AUDIT_PURPOSES,
 };

package/argo/scripts/graph-rag/liveEmbeddingIndexGate.js

@@ -46,7 +46,7 @@ function createLiveEmbeddingIndexGate(dependencies = {}) {
       requireInput(input);
       const vector = await client.embed(input.input);
       if (
-        vector.length !== 1024
+        vector.length !== 1536
         || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
       ) {
         throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');
@@ -79,7 +79,7 @@ function requireApprovedConfiguration(configuration, qualification) {
     || qualification.model !== configuration.embeddingModel
     || qualification.version !== configuration.embeddingModelVersion
     || qualification.dimensions !== configuration.embeddingDimensions
-    || qualification.dimensions !== 1024
+    || qualification.dimensions !== 1536
   ) {
     throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
   }

package/argo/scripts/graph-rag/liveEmbeddingNeo4jBoundary.js

@@ -64,11 +64,11 @@ async function createApprovedNeo4jBoundary({ configuration, neo4j, logger }) {
       return result.records.map(record => normalizeNeo4jValue(record.get('evidence')));
     },
     async queryVectorEvidence(runId, vector, canonicalIdentities) {
-      if (!Array.isArray(vector) || vector.length !== 1024 || !Array.isArray(canonicalIdentities)) {
+      if (!Array.isArray(vector) || vector.length !== 1536 || !Array.isArray(canonicalIdentities)) {
         throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
       }
       await query(
-        'CREATE VECTOR INDEX argo_live_embedding_vector IF NOT EXISTS FOR (e:ArgoLiveEmbeddingEvidence) ON (e.vector) OPTIONS { indexConfig: { `vector.dimensions`: 1024, `vector.similarity_function`: "cosine" } }',
+        'CREATE VECTOR INDEX argo_live_embedding_vector IF NOT EXISTS FOR (e:ArgoLiveEmbeddingEvidence) ON (e.vector) OPTIONS { indexConfig: { `vector.dimensions`: 1536, `vector.similarity_function`: "cosine" } }',
         {},
       );
       const result = await query(

package/argo/scripts/graph-rag/liveEmbeddingProviderConfig.js

@@ -21,6 +21,20 @@ const CONFIG_KEYS = Object.freeze([
 const OPTIONAL_CONFIG_KEYS = Object.freeze([
   'ARGO_NEO4J_DATABASE',
 ]);
+// Semantic-retrieval tuning knobs (purpose-aware thresholds + bounded top-K).
+// They are read by defaultSemanticRetrieval from process.env and whitelisted here
+// so an approved env file may carry them without tripping SECRET_FILE_UNKNOWN_KEY.
+const RETRIEVAL_TUNING_KEYS = Object.freeze([
+  'ARGO_SEMANTIC_MEMORY_THRESHOLD',
+  'ARGO_SEMANTIC_MEMORY_THRESHOLD_ELEMENT',
+  'ARGO_SEMANTIC_MEMORY_THRESHOLD_RELATIONSHIP',
+  'ARGO_SEMANTIC_MEMORY_THRESHOLD_VIEW',
+  'ARGO_SEMANTIC_AUDIT_THRESHOLD',
+  'ARGO_SEMANTIC_AUDIT_THRESHOLD_ELEMENT',
+  'ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP',
+  'ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW',
+  'ARGO_SEMANTIC_TOP_K',
+]);
 const OPT_IN_KEYS = Object.freeze({
   ARGO_LIVE_PROVIDER_E2E: 'LIVE_PROVIDER_E2E_OPT_IN_REQUIRED',
   ARGO_W31_LIVE_MUTATION_VECTOR_E2E: 'W31_MUTATION_VECTOR_E2E_OPT_IN_REQUIRED',
@@ -28,6 +42,7 @@ const OPT_IN_KEYS = Object.freeze({
 const READABLE_KEYS = Object.freeze([
   ...CONFIG_KEYS,
   ...OPTIONAL_CONFIG_KEYS,
+  ...RETRIEVAL_TUNING_KEYS,
   ...Object.keys(OPT_IN_KEYS),
 ]);
 const LEGACY_KEYS = Object.freeze(['ARGO_NEO4J_URI', 'ARGO_NEO4J_USERNAME', 'ARGO_NEO4J_PASSWORD']);
@@ -38,7 +53,7 @@ const APPROVED = Object.freeze({
   ARGO_EMBEDDING_MODEL: 'qwen3.7-text-embedding',
   ARGO_EMBEDDING_PROVIDER: 'alibaba-cloud-model-studio-openai-compatible-cn-beijing',
   ARGO_EMBEDDING_MODEL_VERSION: 'qualification-2026-07-25',
-  ARGO_EMBEDDING_DIMENSIONS: '1024',
+  ARGO_EMBEDDING_DIMENSIONS: '1536',
 });
 const issuedAdapters = new WeakSet();
 const issuedTraces = new WeakSet();
@@ -167,7 +182,7 @@ async function resolveTrusted({
     embeddingModel: normalized.ARGO_EMBEDDING_MODEL,
     embeddingProvider: normalized.ARGO_EMBEDDING_PROVIDER,
     embeddingModelVersion: normalized.ARGO_EMBEDDING_MODEL_VERSION,
-    embeddingDimensions: 1024,
+    embeddingDimensions: 1536,
     neo4jDatabaseUrl: normalized.ARGO_NEO4J_DATABASE_URL,
     neo4jDatabaseUsername: normalized.ARGO_NEO4J_DATABASE_USERNAME,
     neo4jDatabasePassword: normalized.ARGO_NEO4J_DATABASE_PASSWORD,
@@ -342,13 +357,15 @@ function preflightFile({ canonicalFilePath, configuredFilePath, filesystem, adap
     const insideRepository = adapters.systemMetadata.isSecretFileInsideGitRepository().status === 0;
     ignored = insideRepository ? adapters.systemMetadata.isSecretFileIgnored() : true;
     tracked = insideRepository ? adapters.systemMetadata.isSecretFileTracked() : false;
-    const identityResult = adapters.systemMetadata.readCurrentIdentity();
-    const aclResult = adapters.systemMetadata.readSecretFileAcl();
-    aclEvidence = {
-      status: aclResult.status,
-      stdout: aclResult.stdout,
-      identity: identityResult.status === 0 ? identityResult.stdout.trim() : '',
-    };
+    if (process.platform === 'win32') {
+      const identityResult = adapters.systemMetadata.readCurrentIdentity();
+      const aclResult = adapters.systemMetadata.readSecretFileAcl();
+      aclEvidence = {
+        status: aclResult.status,
+        stdout: aclResult.stdout,
+        identity: identityResult.status === 0 ? identityResult.stdout.trim() : '',
+      };
+    }
   } else {
     ignored = adapters.git.isIgnored(configuredFilePath);
     tracked = adapters.git.isTracked(configuredFilePath);
@@ -356,7 +373,11 @@ function preflightFile({ canonicalFilePath, configuredFilePath, filesystem, adap
   }
   if (tracked) throw safeError('SECRET_FILE_TRACKED');
   if (!ignored) throw safeError('SECRET_FILE_NOT_IGNORED');
-  validateAcl(aclEvidence);
+  if (process.platform === 'win32') {
+    validateAcl(aclEvidence);
+  } else {
+    validatePosixSecretFileAcl(configuredFilePath, filesystem);
+  }
 }
 
 function validateAcl(result) {
@@ -389,6 +410,20 @@ function parseAcl(output) {
   return result;
 }
 
+function posixModeIsSecretSafe(mode) {
+  return (mode & 0o077) === 0 && (mode & 0o600) === 0o600;
+}
+
+function validatePosixSecretFileAcl(configuredFilePath, filesystem) {
+  const stat = filesystem.lstatSync(configuredFilePath);
+  if (!posixModeIsSecretSafe(stat.mode)) {
+    throw safeError('SECRET_FILE_ACL_UNSAFE');
+  }
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw safeError('SECRET_FILE_ACL_UNSAFE');
+  }
+}
+
 function productionSourceBehavior(repositoryRoot) {
   return Object.freeze({
     expectedFilePath: getArgoEnvPath(),
@@ -478,4 +513,5 @@ function safeError(category) {
 module.exports = {
   resolveApprovedLiveConfiguration,
   withApprovedLiveConfigurationTestComposition,
+  posixModeIsSecretSafe,
 };

package/argo/scripts/graph-rag/mutationEmbeddingVectorLifecycle.js

@@ -1143,7 +1143,7 @@ function createSyntheticVectorTransport() {
           return {
             data: [
               {
-                embedding: Array.from({ length: 1024 }, (_, index) => index / 2048),
+                embedding: Array.from({ length: 1536 }, (_, index) => index / 2048),
               },
             ],
           };

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticBackfill.js

@@ -15,6 +15,8 @@ function createProductionSemanticBackfill(dependencies = {}) {
   requireBoundary(dependencies.structuralProjection, 'requireComplete', 'structuralProjection');
   requireBoundary(dependencies.embeddingProvider, 'embedBatch', 'embeddingProvider');
   requireBoundary(dependencies.projectionStore, 'upsertRecords', 'projectionStore');
+  requireBoundary(dependencies.projectionStore, 'readRecords', 'projectionStore');
+  requireBoundary(dependencies.projectionStore, 'deleteTombstones', 'projectionStore');
   requireBoundary(dependencies.checkpointStore, 'readCheckpoint', 'checkpointStore');
   requireBoundary(dependencies.checkpointStore, 'writeCheckpoint', 'checkpointStore');
   const batchSize = dependencies.batchSize;
@@ -55,6 +57,11 @@ function createProductionSemanticBackfill(dependencies = {}) {
           checkpointStore: dependencies.checkpointStore,
         });
       }
+      const reconciled = await reconcileRemovals({
+        snapshot,
+        canonicalVersion,
+        projectionStore: dependencies.projectionStore,
+      });
       const aligned = CHANNELS.every(channel => (
         channels[channel].status === 'complete'
         && channels[channel].canonicalVersion === canonicalVersion
@@ -64,6 +71,7 @@ function createProductionSemanticBackfill(dependencies = {}) {
         canonicalVersion,
         alignmentState: aligned ? 'Aligned' : 'Updating',
         channels: Object.freeze(channels),
+        reconciled,
       });
     },
   });
@@ -204,6 +212,39 @@ function mergeFailures(existing, current) {
   return [...merged.values()];
 }
 
+// Full-reconciliation removal pass: after all channels are upserted, delete any
+// persisted semantic record whose canonical identity no longer exists in the
+// local JSON snapshot. This guarantees argo-init rebuilds a semantic projection
+// that is exactly consistent with the canonical graph (no stale vectors).
+async function reconcileRemovals({ snapshot, canonicalVersion, projectionStore }) {
+  const currentByChannel = new Map();
+  for (const channel of CHANNELS) {
+    const source = CHANNEL_SOURCES[channel];
+    const identities = new Set(
+      (snapshot[source.property] || []).map(record => `${channel}:${source.identity(record)}`),
+    );
+    currentByChannel.set(channel, identities);
+  }
+  const stored = await projectionStore.readRecords();
+  const allStored = Array.isArray(stored) ? stored : [];
+  const stale = allStored.filter(record => {
+    const identities = currentByChannel.get(record.channel);
+    return identities && !identities.has(record.canonicalIdentity);
+  });
+  const tombstones = stale.map(record => Object.freeze({
+    canonicalIdentity: record.canonicalIdentity,
+    channel: record.channel,
+    canonicalVersion: record.canonicalVersion || canonicalVersion,
+  }));
+  if (tombstones.length > 0) {
+    await projectionStore.deleteTombstones(tombstones);
+  }
+  return Object.freeze({
+    scanned: allStored.length,
+    tombstoned: tombstones.length,
+  });
+}
+
 function requireBoundary(boundary, method, name) {
   if (!boundary || typeof boundary[method] !== 'function') {
     throw new TypeError(`${name}.${method} is required`);

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticNeo4jAdapter.js

@@ -90,14 +90,31 @@ function createProductionSemanticNeo4jAdapter(dependencies = {}) {
   });
 }
 
+const EMBEDDING_DIMENSIONS = 1536;
+
 async function ensureVectorIndexes(session) {
   for (const definition of Object.values(CHANNEL_INDEXES)) {
+    // CREATE ... IF NOT EXISTS cannot change an existing index's dimensions, so
+    // when the approved embedding dimension changes (e.g. 1024 -> 1536) drop the
+    // stale index first and recreate it at the approved dimension.
+    const existing = await executeRead(
+      session,
+      'SHOW INDEXES YIELD name, type, options WHERE type = \'VECTOR\' AND name = $name RETURN name, options',
+      { name: definition.indexName },
+    );
+    if (existing.records.length > 0) {
+      const options = existing.records[0].get('options');
+      const dim = options && options.indexConfig && options.indexConfig['vector.dimensions'];
+      if (dim !== EMBEDDING_DIMENSIONS) {
+        await executeWrite(session, `DROP INDEX ${definition.indexName} IF EXISTS`, {});
+      }
+    }
     await executeWrite(
       session,
       [
         `CREATE VECTOR INDEX ${definition.indexName} IF NOT EXISTS`,
         `FOR (semantic:${definition.label}) ON (semantic.vector)`,
-        'OPTIONS { indexConfig: { `vector.dimensions`: 1024, `vector.similarity_function`: "cosine" } }',
+        `OPTIONS { indexConfig: { \`vector.dimensions\`: ${EMBEDDING_DIMENSIONS}, \`vector.similarity_function\`: "cosine" } }`,
       ].join('\n'),
       {},
     );

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -128,7 +128,7 @@ const W31_APPROVED_PROFILE = Object.freeze({
   baseUrl: 'https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
   model: 'qwen3.7-text-embedding',
   version: 'qualification-2026-07-25',
-  dimensions: 1024,
+  dimensions: 1536,
   source: 'explicit-human-approval',
 });
 
@@ -406,6 +406,20 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'memory_search',
+    description: 'Semantic memory search: retrieve the user\'s memory by natural-language query. Runs embedding-based semantic retrieval (memory-retrieval purpose) over the intent graph and returns the top-k relevant memory items (id, name, type, similarity score, and a description excerpt with its full length). Each hit is a lightweight card: to keep the tool result compact, description is truncated to max_desc_len characters (default 800) and the full text length is reported as description_length. To read the full text of a hit, call getIntentElementContext with its id. Agents SHOULD call this tool to look up the user\'s memory before answering a question about the user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural-language query describing the user memory to retrieve.' },
+        top_k: { type: 'integer', description: 'Optional max number of hits to return (default 8).' },
+        max_desc_len: { type: 'integer', description: 'Optional max characters of description to return per hit. Default 800. Use 0 for the full description, or -1 to omit description and return only the length.' },
+        architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 // Every tool accepts an optional per-call `workspaceRoot` (absolute path,
@@ -2188,9 +2202,91 @@ async function callTool(name, args = {}, dependencies = undefined) {
     return queryNeo4jGraphTool(args);
   }
 
+  if (name === 'memory_search') {
+    return memorySearchTool(args, dependencies);
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
+// memory_search: natural-language semantic memory retrieval. Reuses the
+// memory-retrieval purpose (implementation-design) of the semantic journey
+// (same path as getSystemArchitecture, so readiness/closure behave identically)
+// and reshapes the retrieved elements into a memory-oriented hit list with
+// content + similarity score, so an agent can look up the user's memory in one
+// call.
+async function memorySearchTool(args = {}, dependencies = undefined) {
+  const query = typeof args.query === 'string' ? args.query.trim() : '';
+  if (!query) {
+    return { status: 'failed', error: { category: 'MEMORY_QUERY_REQUIRED', message: 'query is required' } };
+  }
+  const topK = Number.isInteger(args.top_k) && args.top_k > 0 ? args.top_k : 8;
+  // max_desc_len: default 800 (compact excerpt). 0 = full description;
+  // -1 = omit description entirely and return only the length. Keeps the tool
+  // result compact (production memory cards, not full session dumps).
+  let maxDescLen = 800;
+  if (Number.isInteger(args.max_desc_len) && args.max_desc_len !== 800) {
+    maxDescLen = args.max_desc_len;
+  }
+  const context = await loadContext(args);
+  let retrieved;
+  try {
+    const journey = await resolveSemanticOperatorJourney(dependencies);
+    retrieved = await journey.query({ purpose: 'implementation-design', intent: query });
+  } catch (error) {
+    return {
+      status: 'failed',
+      error: {
+        category: error && error.category ? error.category : 'MEMORY_RETRIEVAL_FAILED',
+        message: error && error.message ? error.message : 'Memory retrieval failed',
+      },
+    };
+  }
+  const source = retrieved && (retrieved.result || retrieved.document) || retrieved;
+  const subset = buildCanonicalSemanticDocumentSubset(source, context.document);
+  if (subset.status !== 'passed') {
+    return { status: 'failed', error: subset.error || { category: 'MEMORY_RETRIEVAL_FAILED' } };
+  }
+  const hits = (Array.isArray(subset.document && subset.document.elements) ? subset.document.elements : [])
+    .filter(element => element && typeof element.semanticScore === 'number')
+    .sort((left, right) => right.semanticScore - left.semanticScore)
+    .slice(0, topK)
+    .map(element => Object.freeze(memoryHitCard(element, maxDescLen)));
+  return {
+    status: 'passed',
+    query,
+    max_desc_len: maxDescLen,
+    fullTextHint: 'To read the full text of a hit, call getIntentElementContext with its id (elementId).',
+    hits: Object.freeze(hits),
+  };
+}
+
+// Build one compact memory hit: id/name/type/score + an excerpt of the
+// description bounded by maxDescLen, plus the full text length so the caller
+// knows how much content exists and can decide whether to expand.
+function memoryHitCard(element, maxDescLen) {
+  const description = typeof element.description === 'string' ? element.description : '';
+  const descriptionLength = description.length;
+  let excerpt = '';
+  if (maxDescLen !== -1) {
+    excerpt = maxDescLen === 0 ? description : description.slice(0, maxDescLen);
+  }
+  const card = {
+    id: element.id,
+    name: element.name,
+    type: element.type,
+    score: element.semanticScore,
+    description_length: descriptionLength,
+  };
+  if (maxDescLen !== -1) {
+    card.description = excerpt;
+    if (maxDescLen > 0 && descriptionLength > maxDescLen) {
+      card.truncated = true;
+    }
+  }
+  return card;
+}
+
 async function queryNeo4jGraphTool(args = {}) {
   const architecturePath = args.architecturePath || DEFAULT_GRAPH_PATH;
   const workspaceRoot = resolveWorkspaceRoot(args);
@@ -2780,15 +2876,52 @@ function buildCanonicalSemanticDocumentSubset(source, canonicalDocument = undefi
     }
   }
 
+  // Attach the semantic similarity score to each retrieved object so callers can
+  // judge relevance (top-K bounded recall may include borderline neighbours).
+  const semanticScoreById = new Map();
+  const seedsByType = evidence.seedsByType || {};
+  for (const channelSeeds of Object.values(seedsByType)) {
+    for (const seed of Array.isArray(channelSeeds) ? channelSeeds : []) {
+      if (!seed || !seed.id) continue;
+      const numericScore = Number(seed.score);
+      if (!Number.isFinite(numericScore)) continue;
+      const bareId = String(seed.id).replace(/^[^:]*:/, '');
+      if (bareId && (!semanticScoreById.has(bareId) || numericScore > semanticScoreById.get(bareId))) {
+        semanticScoreById.set(bareId, numericScore);
+      }
+    }
+  }
+  // buildCanonicalSemanticDocumentSubset may run a second time over a prior
+  // subset document (which no longer carries seedsByType); carry scores forward
+  // from evidence elements that already expose semanticScore.
+  for (const item of evidenceElements) {
+    if (!item) continue;
+    const numericScore = Number(item.semanticScore);
+    if (!Number.isFinite(numericScore)) continue;
+    const key = String(item.id !== undefined ? item.id : item.view_id);
+    if (key && (!semanticScoreById.has(key) || numericScore > semanticScoreById.get(key))) {
+      semanticScoreById.set(key, numericScore);
+    }
+  }
+  const withSemanticScore = item => {
+    if (!item) return item;
+    const score = item.id !== undefined
+      ? semanticScoreById.get(String(item.id))
+      : semanticScoreById.get(String(item.view_id));
+    return typeof score === 'number' ? Object.freeze({ ...item, semanticScore: score }) : item;
+  };
   const elements = [...elementIds]
     .map(id => canonicalElementById.get(id))
-    .filter(Boolean);
+    .filter(Boolean)
+    .map(withSemanticScore);
   const relationships = [...relationshipIds]
     .map(id => canonicalRelationshipById.get(id))
-    .filter(Boolean);
+    .filter(Boolean)
+    .map(withSemanticScore);
   const views = [...viewIds]
     .map(id => canonicalViewById.get(id))
-    .filter(Boolean);
+    .filter(Boolean)
+    .map(withSemanticScore);
 
   return {
     status: 'passed',
@@ -3483,6 +3616,7 @@ module.exports = {
   handleRequest,
   loadContext,
   main,
+  memoryHitCard,
   resolveSemanticScope,
   validateDocument,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.31",
+  "version": "0.10.33",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {