@ivotoby/postgram-cli 1.29.0 → 1.30.1

package/README.md

@@ -30,6 +30,16 @@ pgm store "decided to use pgvector" --type memory --tags "decisions,architecture
 # Search
 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
+pgm list --json                                        # compact JSON rows
+pgm list --json --full-response                        # full API-shaped rows
+pgm list --toon                                        # compact TOON rows
+pgm expand <entity-id> --json                          # compact graph JSON
+pgm expand <entity-id> --toon                          # compact TOON graph
+
 # Recall by ID
 pgm recall <entity-id>
 
@@ -63,6 +73,14 @@ pgm queue
 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
+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.
+
 ## Memory Roles
 
 Store durable memory:

package/dist/client.js

@@ -49,6 +49,12 @@ export function createPgmClient(options) {
                 body: input
             });
         },
+        groomSessionContext(input) {
+            return request(options, '/api/memory/session-context/groom', {
+                method: 'POST',
+                body: input
+            });
+        },
         recallEntity(id, input = {}) {
             const params = new URLSearchParams();
             if (input.owner) {

package/dist/pgm.js

@@ -9,6 +9,7 @@ import { createPgmClient } from './client.js';
 import { handleCliFailure, isJsonMode, parseCommaList, parseJsonObject, printHuman, printJson, readStdinText, resolvePgmConfig, shortId } from './shared.js';
 import { AppError, ErrorCode } from './errors.js';
 import { buildSyncManifest } from './sync-walk.js';
+import { compactEdgeResponse, compactEntityListResponse, compactGraphResponse, compactSearchResponse, compactStoredEntityResponse, entityListResponseToToon, graphResponseToToon, searchResponseToToon } from './search-output.js';
 function formatStoredEntity(entity) {
     return [
         `${entity.type} ${shortId(entity.id)}${entity.status ? ` [${entity.status}]` : ''}`,
@@ -26,7 +27,8 @@ 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) {
+        if (result.entity.content &&
+            result.entity.content !== result.chunk_content) {
             lines.push(`  entity: ${result.entity.content}`);
         }
         if (result.related && result.related.length > 0) {
@@ -57,6 +59,48 @@ function formatTaskList(items) {
         ];
     });
 }
+function validateToonOptions(options, json) {
+    if (options.toon === true && (json || options.fullResponse === true)) {
+        throw new AppError(ErrorCode.VALIDATION, '--toon cannot be combined with --json or --full-response');
+    }
+}
+function parseDurationMs(value) {
+    const match = /^(\d+)([mhd])$/i.exec(value.trim());
+    if (!match) {
+        throw new AppError(ErrorCode.VALIDATION, `Invalid duration '${value}'. Use format like '15m', '2h', or '7d'.`);
+    }
+    const [, amountText, unitText] = match;
+    const amount = Number(amountText);
+    const unit = unitText.toLowerCase();
+    const milliseconds = unit === 'm'
+        ? amount * 60 * 1000
+        : unit === 'h'
+            ? amount * 60 * 60 * 1000
+            : amount * 24 * 60 * 60 * 1000;
+    if (milliseconds > 3650 * 24 * 60 * 60 * 1000) {
+        throw new AppError(ErrorCode.VALIDATION, `Duration '${value}' exceeds the maximum allowed (3650 days / ~10 years).`);
+    }
+    return milliseconds;
+}
+function formatGroomCandidates(candidates) {
+    if (candidates.length === 0) {
+        return ['No eligible session-context memories'];
+    }
+    const lines = [`Would archive ${candidates.length} session-context memories`];
+    for (const candidate of candidates) {
+        const metadata = candidate.metadata;
+        lines.push([
+            `  ${shortId(candidate.id)} ${candidate.createdAt.slice(0, 10)}`,
+            candidate.tags.length ? `tags=${candidate.tags.join(',')}` : 'tags=-',
+            metadata.topic ? `topic=${metadata.topic}` : undefined,
+            metadata.session_id ? `session=${metadata.session_id}` : undefined,
+            candidate.content ? `content=${candidate.content}` : 'content=-'
+        ]
+            .filter(Boolean)
+            .join(' | '));
+    }
+    return lines;
+}
 async function resolveStoreContent(content) {
     if (content !== undefined) {
         return content;
@@ -209,6 +253,7 @@ program
     .option('--source <source>', 'entity source')
     .option('--metadata <json>', 'JSON metadata object')
     .option('--skip-extraction', 'store without ever queueing graph extraction')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (content, options, command) => {
     await runWithClient(command, async (client, json) => {
         const body = await client.storeEntity({
@@ -223,7 +268,9 @@ program
             skip_extraction: options.skipExtraction === true ? true : undefined
         });
         return json
-            ? body
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
             : formatStoredEntity({
                 id: body.entity.id,
                 type: body.entity.type,
@@ -249,9 +296,13 @@ 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: durable_memory or session_context')
-    .option('--include-other-clients-session-context', 'include session context from other clients')
+    .option('--full-response', 'emit the full API response instead of compact default output 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) => {
+        if (options.toon === true && (json || options.fullResponse === true)) {
+            throw new AppError(ErrorCode.VALIDATION, '--toon cannot be combined with --json or --full-response');
+        }
         if (options.memoryRole !== undefined &&
             !['durable_memory', 'session_context'].includes(options.memoryRole)) {
             throw new AppError(ErrorCode.VALIDATION, '--memory-role must be durable_memory or session_context');
@@ -267,15 +318,66 @@ program
             recency_weight: Number(options.recencyWeight),
             expand_graph: options.expandGraph === true ? true : undefined,
             include_archived: options.includeArchived === true ? true : undefined,
-            memory_role: options.memoryRole,
-            include_other_clients_session_context: options.includeOtherClientsSessionContext === true ? true : undefined
+            memory_role: options.memoryRole
         });
-        return json ? body : formatSearchResults(body.results);
+        if (options.toon === true) {
+            return searchResponseToToon(compactSearchResponse(body));
+        }
+        if (json) {
+            return options.fullResponse === true
+                ? body
+                : compactSearchResponse(body);
+        }
+        return formatSearchResults(body.results);
     });
 });
 const memoryCommand = program
     .command('memory')
     .description('Memory-specific commands');
+memoryCommand
+    .command('groom')
+    .description('Preview or archive stale session-context memories for the authenticated client')
+    .option('--dry-run', 'preview without mutating')
+    .option('--older-than <duration>', 'only include memories older than this (e.g. 15m, 2h, 7d)', '7d')
+    .option('--limit <limit>', 'maximum candidates', '50')
+    .option('--topic <topic>', 'filter by topic')
+    .option('--session-id <sessionId>', 'filter by session id')
+    .option('--tag <tag>', 'filter by tag (repeatable)', (value, previous = []) => {
+    previous.push(value);
+    return previous;
+}, [])
+    .option('--yes', 'confirm archive mutation')
+    .action(async (options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const limit = Number.parseInt(options.limit, 10);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new AppError(ErrorCode.VALIDATION, '--limit must be a positive integer');
+        }
+        if (options.dryRun !== true && options.yes !== true) {
+            throw new AppError(ErrorCode.VALIDATION, '--yes is required outside dry-run');
+        }
+        const body = await client.groomSessionContext({
+            dry_run: options.dryRun === true,
+            confirmed: options.dryRun === true ? undefined : true,
+            older_than_ms: parseDurationMs(options.olderThan),
+            limit,
+            topic: options.topic,
+            session_id: options.sessionId,
+            tags: options.tag
+        });
+        if (json) {
+            return body;
+        }
+        if (body.dryRun) {
+            return formatGroomCandidates(body.eligible ?? []);
+        }
+        return [
+            `Archived ${body.archived} session-context memories`,
+            `  promoted: ${body.promoted}`,
+            `  skipped: ${body.skipped}`
+        ];
+    });
+});
 memoryCommand
     .command('session-context')
     .alias('session')
@@ -290,6 +392,7 @@ memoryCommand
     .option('--promotable', 'mark this session context as promotable')
     .option('--groom-after <groomAfter>', 'ISO timestamp after which grooming may archive/promote it')
     .option('--expires-at <expiresAt>', 'ISO timestamp after which the context is stale')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (content, options, command) => {
     await runWithClient(command, async (client, json) => {
         const body = await client.storeSessionContext({
@@ -305,7 +408,9 @@ memoryCommand
             expires_at: options.expiresAt
         });
         return json
-            ? body
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
             : formatStoredEntity({
                 id: body.entity.id,
                 type: body.entity.type,
@@ -341,8 +446,11 @@ program
     .option('--limit <limit>', 'result limit', '50')
     .option('--offset <offset>', 'result offset', '0')
     .option('--include-archived', 'include archived entities')
+    .option('--full-response', 'emit the full API response instead of compact default output 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 (options, command) => {
     await runWithClient(command, async (client, json) => {
+        validateToonOptions(options, json);
         const body = await client.listEntities({
             type: options.type,
             status: options.status,
@@ -353,8 +461,13 @@ program
             offset: Number(options.offset),
             include_archived: options.includeArchived === true ? true : undefined
         });
+        if (options.toon === true) {
+            return entityListResponseToToon(compactEntityListResponse(body));
+        }
         if (json) {
-            return body;
+            return options.fullResponse === true
+                ? body
+                : compactEntityListResponse(body);
         }
         if (body.items.length === 0) {
             return ['No entities'];
@@ -387,6 +500,7 @@ program
     .option('--metadata <json>', 'JSON metadata object')
     .option('--version <version>', 'expected version')
     .option('--force', 'retry using the latest version on conflict')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (id, options, command) => {
     await runWithClient(command, async (client, json) => {
         const payload = {
@@ -412,7 +526,11 @@ program
         else {
             throw new Error('--version is required unless --force is set');
         }
-        return json ? body : formatStoredEntity(body.entity);
+        return json
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
+            : formatStoredEntity(body.entity);
     });
 });
 program
@@ -436,6 +554,7 @@ taskCommand
     .option('--tags <tags>', 'comma-separated tags')
     .option('--visibility <visibility>', 'task visibility', 'shared')
     .option('--metadata <json>', 'JSON metadata object')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (content, options, command) => {
     await runWithClient(command, async (client, json) => {
         const taskContent = await resolveStoreContent(content);
@@ -449,7 +568,9 @@ taskCommand
             metadata: parseJsonObject(options.metadata)
         });
         return json
-            ? body
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
             : formatStoredEntity({
                 id: body.entity.id,
                 type: body.entity.type,
@@ -469,8 +590,11 @@ taskCommand
     .option('--limit <limit>', 'result limit', '50')
     .option('--offset <offset>', 'result offset', '0')
     .option('--include-archived', 'include archived tasks')
+    .option('--full-response', 'emit the full API response instead of compact default output 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 (options, command) => {
     await runWithClient(command, async (client, json) => {
+        validateToonOptions(options, json);
         const body = await client.listTasks({
             status: options.status,
             context: options.context,
@@ -478,7 +602,14 @@ taskCommand
             offset: Number(options.offset),
             include_archived: options.includeArchived === true ? true : undefined
         });
-        return json ? body : formatTaskList(body.items);
+        if (options.toon === true) {
+            return entityListResponseToToon(compactEntityListResponse(body));
+        }
+        return json
+            ? options.fullResponse === true
+                ? body
+                : compactEntityListResponse(body)
+            : formatTaskList(body.items);
     });
 });
 taskCommand
@@ -493,6 +624,7 @@ taskCommand
     .option('--visibility <visibility>', 'updated task visibility')
     .option('--metadata <json>', 'JSON metadata object')
     .option('--version <version>', 'expected version', '')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (id, options, command) => {
     await runWithClient(command, async (client, json) => {
         if (!options.version) {
@@ -509,7 +641,9 @@ taskCommand
             metadata: parseJsonObject(options.metadata)
         });
         return json
-            ? body
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
             : formatStoredEntity({
                 id: body.entity.id,
                 type: body.entity.type,
@@ -526,6 +660,7 @@ taskCommand
     .description('Mark a task complete')
     .argument('id', 'task ID')
     .option('--version <version>', 'expected version')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (id, options, command) => {
     await runWithClient(command, async (client, json) => {
         if (options.version === undefined) {
@@ -533,7 +668,9 @@ taskCommand
         }
         const body = await client.completeTask(id, Number(options.version));
         return json
-            ? body
+            ? options.fullResponse === true
+                ? body
+                : compactStoredEntityResponse(body)
             : formatStoredEntity({
                 id: body.entity.id,
                 type: body.entity.type,
@@ -554,7 +691,9 @@ program
         if (json)
             return body;
         const e = body.embedding;
-        const age = e.oldest_pending_secs !== null ? ` oldest_pending=${e.oldest_pending_secs}s` : '';
+        const age = e.oldest_pending_secs !== null
+            ? ` oldest_pending=${e.oldest_pending_secs}s`
+            : '';
         const lines = [
             `embedding:  pending=${e.pending}  completed=${e.completed}  failed=${e.failed}  retry_eligible=${e.retry_eligible}${age}`
         ];
@@ -603,8 +742,14 @@ program
         const manifest = await buildSyncManifest(resolvedDir);
         const config = await resolvePgmConfig();
         const client = createPgmClient(config);
-        const manifestForServer = manifest.map(({ path: p, sha }) => ({ path: p, sha }));
-        const diff = await client.diffSync({ repo: repoName, files: manifestForServer });
+        const manifestForServer = manifest.map(({ path: p, sha }) => ({
+            path: p,
+            sha
+        }));
+        const diff = await client.diffSync({
+            repo: repoName,
+            files: manifestForServer
+        });
         if (options.dryRun) {
             const newCount = diff.toUpload.filter((f) => f.reason === 'new').length;
             const changedCount = diff.toUpload.filter((f) => f.reason === 'changed').length;
@@ -650,7 +795,8 @@ program
             }
             const content = await fsReadFile(entry.fullPath, 'utf8');
             const size = Buffer.byteLength(content, 'utf8');
-            if (batch.length > 0 && (batch.length >= BATCH_FILES || batchBytes + size > BATCH_BYTES)) {
+            if (batch.length > 0 &&
+                (batch.length >= BATCH_FILES || batchBytes + size > BATCH_BYTES)) {
                 await flushBatch();
             }
             batch.push({ path: toUpload.path, sha: toUpload.sha, content });
@@ -687,6 +833,7 @@ program
     .argument('<target-id>', 'target entity ID')
     .requiredOption('--relation <relation>', 'relationship type')
     .option('--confidence <n>', 'confidence score 0-1', '1.0')
+    .option('--full-response', 'emit the full API response when used with --json')
     .action(async (sourceId, targetId, options, command) => {
     await runWithClient(command, async (client, json) => {
         const body = await client.createEdge({
@@ -695,9 +842,12 @@ program
             relation: options.relation,
             confidence: Number(options.confidence)
         });
-        if (json)
-            return body;
-        return [`Linked ${shortId(sourceId)} → ${shortId(targetId)} (${options.relation})`];
+        if (json) {
+            return options.fullResponse === true ? body : compactEdgeResponse(body);
+        }
+        return [
+            `Linked ${shortId(sourceId)} → ${shortId(targetId)} (${options.relation})`
+        ];
     });
 });
 program
@@ -717,16 +867,25 @@ program
     .option('--depth <n>', 'traversal depth (1-3)', '1')
     .option('--relation <types>', 'comma-separated relation types')
     .option('--owner <owner>', 'owner filter')
+    .option('--full-response', 'emit the full API response instead of compact default output 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 (entityId, options, command) => {
     await runWithClient(command, async (client, json) => {
+        validateToonOptions(options, json);
         const relationTypes = parseCommaList(options.relation);
         const body = await client.expandGraph(entityId, {
             depth: Number(options.depth),
             ...(relationTypes !== undefined ? { relationTypes } : {}),
             ...(options.owner !== undefined ? { owner: options.owner } : {})
         });
-        if (json)
-            return body;
+        if (options.toon === true) {
+            return graphResponseToToon(compactGraphResponse(body));
+        }
+        if (json) {
+            return options.fullResponse === true
+                ? body
+                : compactGraphResponse(body);
+        }
         const lines = [];
         lines.push(`Graph for ${shortId(entityId)}:`);
         lines.push(`  ${body.entities.length} entities, ${body.edges.length} edges`);

package/dist/search-output.js

@@ -0,0 +1,170 @@
+export function compactStoredEntity(entity, options = {}) {
+    return {
+        id: entity.id,
+        type: entity.type,
+        ...(entity.version !== undefined ? { version: entity.version } : {}),
+        ...(options.includeContent ? { content: entity.content } : {}),
+        ...(entity.status ? { status: entity.status } : {}),
+        ...(entity.visibility ? { visibility: entity.visibility } : {}),
+        ...(entity.owner ? { owner: entity.owner } : {}),
+        ...(entity.enrichment_status
+            ? { enrichment_status: entity.enrichment_status }
+            : {}),
+        ...(entity.tags?.length ? { tags: entity.tags } : {}),
+        ...(entity.source ? { source: entity.source } : {})
+    };
+}
+export function compactStoredEntityResponse(response) {
+    return {
+        entity: compactStoredEntity(response.entity)
+    };
+}
+export function compactEntityListResponse(response) {
+    return {
+        items: response.items.map((entity) => compactStoredEntity(entity, { includeContent: true })),
+        total: response.total,
+        limit: response.limit,
+        offset: response.offset
+    };
+}
+export function compactEdge(edge) {
+    return {
+        id: edge.id,
+        source_id: edge.source_id,
+        target_id: edge.target_id,
+        relation: edge.relation,
+        ...(edge.confidence !== undefined ? { confidence: edge.confidence } : {})
+    };
+}
+export function compactEdgeResponse(response) {
+    return {
+        edge: compactEdge(response.edge)
+    };
+}
+export function compactGraphResponse(response) {
+    return {
+        entities: response.entities.map((entity) => ({
+            id: entity.id,
+            type: entity.type,
+            content: entity.content
+        })),
+        edges: response.edges.map(compactEdge)
+    };
+}
+export function compactSearchResponse(response) {
+    return {
+        results: response.results.map((entry) => ({
+            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.related?.length
+                ? {
+                    related: entry.related.map((related) => ({
+                        id: related.entity.id,
+                        type: related.entity.type,
+                        relation: related.relation,
+                        direction: related.direction,
+                        content: related.entity.content
+                    }))
+                }
+                : {})
+        }))
+    };
+}
+function toonScalar(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    let scalar;
+    if (Array.isArray(value)) {
+        scalar = value.join('|');
+    }
+    else if (typeof value === 'object') {
+        scalar = JSON.stringify(value);
+    }
+    else if (typeof value === 'string') {
+        scalar = value;
+    }
+    else if (typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint') {
+        scalar = value.toString();
+    }
+    else {
+        scalar = JSON.stringify(value);
+    }
+    return /[,\n\r"]/u.test(scalar) ? JSON.stringify(scalar) : scalar;
+}
+export function searchResponseToToon(response) {
+    const lines = [
+        `results[${response.results.length}]{id,type,score,content,chunk,tags,related}:`
+    ];
+    for (const result of response.results) {
+        lines.push([
+            result.id,
+            result.type,
+            Number.isFinite(result.score)
+                ? Number(result.score.toFixed(6))
+                : result.score,
+            result.content,
+            result.chunk,
+            result.tags,
+            result.related?.length ? `${result.related.length} related` : ''
+        ]
+            .map(toonScalar)
+            .join(','));
+        if (result.related?.length) {
+            lines.push(`  related[${result.related.length}]{id,type,relation,direction,content}:`);
+            for (const related of result.related) {
+                lines.push(`  ${[
+                    related.id,
+                    related.type,
+                    related.relation,
+                    related.direction,
+                    related.content
+                ]
+                    .map(toonScalar)
+                    .join(',')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function entityListResponseToToon(response) {
+    const lines = [
+        `items[${response.items.length}]{id,type,status,version,content,tags,owner}:`
+    ];
+    for (const item of response.items) {
+        lines.push([
+            item.id,
+            item.type,
+            item.status,
+            item.version,
+            item.content,
+            item.tags,
+            item.owner
+        ]
+            .map(toonScalar)
+            .join(','));
+    }
+    lines.push(`total,${response.total}`);
+    lines.push(`limit,${response.limit}`);
+    lines.push(`offset,${response.offset}`);
+    return lines.join('\n');
+}
+export function graphResponseToToon(response) {
+    const lines = [`entities[${response.entities.length}]{id,type,content}:`];
+    for (const entity of response.entities) {
+        lines.push([entity.id, entity.type, entity.content].map(toonScalar).join(','));
+    }
+    lines.push(`edges[${response.edges.length}]{id,source_id,target_id,relation,confidence}:`);
+    for (const edge of response.edges) {
+        lines.push([edge.id, edge.source_id, edge.target_id, edge.relation, edge.confidence]
+            .map(toonScalar)
+            .join(','));
+    }
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivotoby/postgram-cli",
-  "version": "1.29.0",
+  "version": "1.30.1",
   "description": "Postgram CLI — store, search, and manage entities from the command line",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",