@ivotoby/postgram-cli 1.36.1 → 1.37.0

package/README.md

@@ -31,10 +31,11 @@ pgm store "decided to use pgvector" --type memory --tags "decisions,architecture
 # Search with human output
 pgm search "pgvector decisions" --limit 5
 
-# Agent-friendly output formats
-pgm search "pgvector decisions" --json                 # compact JSON by default
-pgm search "pgvector decisions" --json --full-response # full API-shaped JSON
-pgm search "pgvector decisions" --toon                 # compact TOON output
+# Agent-friendly discovery, then selective full retrieval
+pgm search "pgvector decisions" --limit 5 --json       # matched chunks by default
+pgm search "pgvector decisions" --limit 5 --toon       # smallest discovery output
+pgm recall <selected-entity-id>                         # complete selected content
+pgm search "pgvector decisions" --json --full-response # complete legacy response
 pgm list --json                                        # compact JSON rows
 pgm list --json --full-response                        # full API-shaped rows
 pgm list --toon                                        # compact TOON rows
@@ -75,9 +76,12 @@ pgm store "hello" --json
 ```
 
 Agent-facing `--json` output is compact by default for search, list, task list,
-graph expansion, write acknowledgements, and link acknowledgements. It omits
-token-heavy fields such as timestamps, metadata, nested `entity` objects, and
-raw similarity unless you pass `--full-response`. Use `--toon` on list-like
+graph expansion, write acknowledgements, and link acknowledgements. Search
+returns identifiers, 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
 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.
@@ -93,6 +97,8 @@ Compact search may include an `edges` summary:
 
 `edges.count` and `edges.relations` are traversal affordances. They tell an
 agent that graph context exists without returning neighbor content. Use
+`--full-response` only when a machine consumer needs the complete legacy search
+envelope, not as a substitute for recalling one selected result. Use
 `--expand-graph` or `pgm expand <entity-id>` when the user asks about causes,
 provenance, decisions, dependencies, blockers, ownership, involvement,
 discussion participants, connected context, or ambiguous search hits. Do not

package/dist/pgm.js

@@ -39,10 +39,6 @@ function formatSearchResults(results) {
     for (const result of results) {
         lines.push(`${result.entity.type} ${shortId(result.entity.id)} score=${result.score.toFixed(3)}`);
         lines.push(`  ${result.chunk_content}`);
-        if (result.entity.content &&
-            result.entity.content !== result.chunk_content) {
-            lines.push(`  entity: ${result.entity.content}`);
-        }
         if (result.related && result.related.length > 0) {
             lines.push(`  related (${result.related.length}):`);
             for (const rel of result.related) {
@@ -296,7 +292,7 @@ program
 });
 program
     .command('search')
-    .description('Search stored entities (compact JSON with --json; TOON with --toon)')
+    .description('Search stored entities (chunks by default; full content with --json --full-response)')
     .argument('query', 'search query')
     .option('--type <type>', 'entity type')
     .option('--tags <tags>', 'comma-separated tags')
@@ -308,7 +304,7 @@ program
     .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')
-    .option('--full-response', 'emit the full API response instead of compact default output when used with --json')
+    .option('--full-response', 'emit the full API response with complete entity content when used with --json')
     .option('--toon', 'emit compact TOON output for lower agent token use; formatting is applied in the CLI, not the API')
     .action(async (query, options, command) => {
     await runWithClient(command, async (client, json) => {
@@ -330,7 +326,8 @@ program
             recency_weight: Number(options.recencyWeight),
             expand_graph: options.expandGraph === true ? true : undefined,
             include_archived: options.includeArchived === true ? true : undefined,
-            memory_role: options.memoryRole
+            memory_role: options.memoryRole,
+            include_content: options.fullResponse === true
         });
         if (options.toon === true) {
             return searchResponseToToon(compactSearchResponse(body));

package/dist/search-output.js

@@ -57,7 +57,6 @@ export function compactSearchResponse(response) {
             id: entry.entity.id,
             type: entry.entity.type,
             score: entry.score,
-            content: entry.entity.content,
             chunk: entry.chunk_content,
             ...(entry.entity.tags?.length ? { tags: entry.entity.tags } : {}),
             ...(entry.edges ? { edges: entry.edges } : {}),
@@ -67,8 +66,7 @@ export function compactSearchResponse(response) {
                         id: related.entity.id,
                         type: related.entity.type,
                         relation: related.relation,
-                        direction: related.direction,
-                        content: related.entity.content
+                        direction: related.direction
                     }))
                 }
                 : {})
@@ -110,7 +108,7 @@ function formatEdgeSummary(edges) {
 }
 export function searchResponseToToon(response) {
     const lines = [
-        `results[${response.results.length}]{id,type,score,content,chunk,tags,edges,related}:`
+        `results[${response.results.length}]{id,type,score,chunk,tags,edges,related}:`
     ];
     for (const result of response.results) {
         lines.push([
@@ -119,7 +117,6 @@ export function searchResponseToToon(response) {
             Number.isFinite(result.score)
                 ? Number(result.score.toFixed(6))
                 : result.score,
-            result.content,
             result.chunk,
             result.tags,
             formatEdgeSummary(result.edges),
@@ -128,14 +125,13 @@ export function searchResponseToToon(response) {
             .map(toonScalar)
             .join(','));
         if (result.related?.length) {
-            lines.push(`  related[${result.related.length}]{id,type,relation,direction,content}:`);
+            lines.push(`  related[${result.related.length}]{id,type,relation,direction}:`);
             for (const related of result.related) {
                 lines.push(`  ${[
                     related.id,
                     related.type,
                     related.relation,
-                    related.direction,
-                    related.content
+                    related.direction
                 ]
                     .map(toonScalar)
                     .join(',')}`);

package/package.json

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