@ivotoby/postgram-cli 1.37.2 → 1.37.3

package/README.md

@@ -75,13 +75,30 @@ pgm queue
 pgm store "hello" --json
 ```
 
+Search retrieves both semantic vector neighbors and chunks matching query
+keywords. Whitespace-separated terms are ORed; each term's `simple` lexemes
+are ANDed, preserving compound identifiers such as `ABC-1234`. For multi-term
+queries, standalone English stopwords are omitted using the English dictionary;
+matching and ranking still use the `simple` configuration. This lets a chunk
+matching one complete term enter the bounded candidate set for a long query.
+It deduplicates chunks and ranks the candidates with reciprocal-rank fusion
+(RRF): `1 / (60 + vector_rank) + 1 / (60 + keyword_rank)`, with a missing
+branch contributing zero. The `--threshold` value is a cosine similarity
+floor; below-floor keyword matches need at least half of the retained distinct
+query terms, rounded up. A single-term query, including a compound identifier,
+requires its one retained term.
+Human-readable scores are relative RRF values, printed with six decimal places,
+and are not percentages. A candidate ranked first in both branches scores about
+`0.03279` before recency. Equal final scores prefer the lower keyword rank,
+then vector rank, then stable identifiers.
+
 Agent-facing `--json` output is compact by default for search, list, task list,
 graph expansion, write acknowledgements, and link acknowledgements. Search
-returns identifiers, scores, matched chunks, tags, and edge summaries without
+returns identifiers, numeric RRF scores, matched chunks, tags, and edge summaries without
 complete result or graph-neighbor content. Select an ID from those chunks and
 use `pgm recall <id>` when complete content is needed. Other compact outputs
 omit token-heavy fields such as timestamps, metadata, nested `entity` objects,
-and raw similarity unless you pass `--full-response`. Use `--toon` on list-like
+and raw cosine similarity unless you pass `--full-response`. Use `--toon` on list-like
 commands (`search`, `list`, `task list`, `expand`) when an agent needs the
 smallest readable output. TOON and compacting are CLI-layer formats; the
 Postgram API remains JSON.

package/dist/pgm.js

@@ -37,7 +37,7 @@ function formatSearchResults(results) {
     }
     const lines = [];
     for (const result of results) {
-        lines.push(`${result.entity.type} ${shortId(result.entity.id)} score=${result.score.toFixed(3)}`);
+        lines.push(`${result.entity.type} ${shortId(result.entity.id)} score=${result.score.toFixed(6)}`);
         lines.push(`  ${result.chunk_content}`);
         if (result.related && result.related.length > 0) {
             lines.push(`  related (${result.related.length}):`);
@@ -292,15 +292,16 @@ program
 });
 program
     .command('search')
-    .description('Search stored entities (chunks by default; full content with --json --full-response)')
+    .description('Hybrid vector + keyword search over stored entity chunks.')
+    .addHelpText('after', '\nRRF scores use 1/(60+vector_rank) + 1/(60+keyword_rank); a missing branch contributes zero. Scores are relative numbers (about 0.03279 when ranked first in both branches before recency), not percentages. --threshold is a cosine similarity floor; keyword chunks covering at least half the keyword terms (rounded up) may pass below it. A single-term query, including a compound identifier, requires its one retained term. Whitespace-separated keyword terms are ORed, while simple lexemes within each term are ANDed so compound identifiers such as ABC-1234 remain intact. Keyword parsing retains the first 24 distinct non-empty terms after multi-term English stopword filtering; embedding uses the full original query.\n')
     .argument('query', 'search query')
     .option('--type <type>', 'entity type')
     .option('--tags <tags>', 'comma-separated tags')
     .option('--visibility <visibility>', 'entity visibility filter')
     .option('--owner <owner>', 'entity owner filter')
     .option('--limit <limit>', 'result limit', '10')
-    .option('--threshold <threshold>', 'similarity threshold', '0.35')
-    .option('--recency-weight <recencyWeight>', 'recency weight', '0.1')
+    .option('--threshold <threshold>', 'cosine similarity floor; below-floor keyword chunks need at least half the keyword terms', '0.35')
+    .option('--recency-weight <recencyWeight>', 'recency multiplier (RRF score uses a 30-day half-life)', '0.1')
     .option('--expand-graph', 'include graph-connected entities in results')
     .option('--include-archived', 'include archived entities in results')
     .option('--memory-role <role>', 'memory role filter: session_context for continuity; durable_memory for stable facts')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivotoby/postgram-cli",
-  "version": "1.37.2",
+  "version": "1.37.3",
   "description": "Postgram CLI — store, search, and manage entities from the command line",
   "type": "module",
   "bin": {