@ivotoby/postgram-cli 1.30.1 → 1.32.0

package/README.md

@@ -1,6 +1,7 @@
 # @ivotoby/postgram-cli
 
-Command-line client for [Postgram](https://github.com/ivo-toby/postgram/).
+Command-line client for [Postgram](https://github.com/ivo-toby/postgram/) built
+for both humans and agents.
 
 ## Install
 
@@ -24,10 +25,10 @@ echo '{"api_url":"http://localhost:3100","api_key":"your-api-key"}' > ~/.pgmrc
 ## Usage
 
 ```bash
-# Store an entity
+# Store durable memory
 pgm store "decided to use pgvector" --type memory --tags "decisions,architecture"
 
-# Search
+# Search with human output
 pgm search "pgvector decisions" --limit 5
 
 # Agent-friendly output formats
@@ -69,7 +70,7 @@ pgm sync ./notes --repo my-notes
 # Check enrichment/extraction queue status
 pgm queue
 
-# JSON output (all commands)
+# Compact JSON output where supported
 pgm store "hello" --json
 ```
 

package/dist/pgm.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import { createWriteStream } from 'node:fs';
+import { createWriteStream, readFileSync } from 'node:fs';
 import { mkdir, readFile as fsReadFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { Command } from 'commander';
@@ -10,6 +10,11 @@ import { handleCliFailure, isJsonMode, parseCommaList, parseJsonObject, printHum
 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 readCliVersion() {
+    const rawPackageJson = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const packageJson = JSON.parse(rawPackageJson);
+    return packageJson.version;
+}
 function formatStoredEntity(entity) {
     return [
         `${entity.type} ${shortId(entity.id)}${entity.status ? ` [${entity.status}]` : ''}`,
@@ -238,15 +243,16 @@ async function runBackup(output, encrypt) {
 const program = new Command();
 program
     .name('pgm')
-    .description('Postgram human CLI')
-    .option('--json', 'emit JSON output');
+    .description('Postgram CLI for humans and agents')
+    .version(readCliVersion())
+    .option('--json', 'emit compact JSON for agents where supported');
 program
     .command('store')
     .alias('add')
-    .description('Store an entity')
+    .description('Store durable memory/entity; use memory session-context for resumability')
     .argument('[content]', 'entity content')
     .option('--type <type>', 'entity type', 'memory')
-    .option('--visibility <visibility>', 'entity visibility', 'shared')
+    .option('--visibility <visibility>', 'entity visibility (prefer personal for agent memory)', 'shared')
     .option('--owner <owner>', 'entity owner or namespace')
     .option('--status <status>', 'entity status')
     .option('--tags <tags>', 'comma-separated tags')
@@ -284,7 +290,7 @@ program
 });
 program
     .command('search')
-    .description('Search stored entities')
+    .description('Search stored entities (compact JSON with --json; TOON with --toon)')
     .argument('query', 'search query')
     .option('--type <type>', 'entity type')
     .option('--tags <tags>', 'comma-separated tags')
@@ -295,7 +301,7 @@ program
     .option('--recency-weight <recencyWeight>', 'recency weight', '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: durable_memory or session_context')
+    .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('--toon', 'emit compact TOON output for lower agent token use; formatting is applied in the CLI, not the API')
     .action(async (query, options, command) => {
@@ -333,7 +339,7 @@ program
 });
 const memoryCommand = program
     .command('memory')
-    .description('Memory-specific commands');
+    .description('Memory commands for agent session context');
 memoryCommand
     .command('groom')
     .description('Preview or archive stale session-context memories for the authenticated client')
@@ -381,12 +387,12 @@ memoryCommand
 memoryCommand
     .command('session-context')
     .alias('session')
-    .description('Store client-scoped session-context memory')
+    .description('Store client-scoped session context for agent resumability')
     .argument('[content]', 'session context content')
-    .option('--visibility <visibility>', 'entity visibility', 'shared')
+    .option('--visibility <visibility>', 'entity visibility (prefer personal for agent session context)', 'shared')
     .option('--owner <owner>', 'entity owner or namespace')
     .option('--session-id <sessionId>', 'external session or thread id')
-    .option('--agent-id <agentId>', 'agent or persona id')
+    .option('--agent-id <agentId>', 'agent/persona metadata only; not an auth boundary')
     .option('--topic <topic>', 'topic label')
     .option('--tags <tags>', 'comma-separated tags')
     .option('--promotable', 'mark this session context as promotable')

package/package.json

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