snipara-companion 1.3.4 → 1.3.6

package/README.md

@@ -41,7 +41,7 @@ For Codex, the primary integration remains Hosted MCP plus `AGENTS.md`.
 
 ## Configuring MCP Tool Surfaces
 
-The MCP server advertises different tool surfaces depending on the `SNIPARA_EXPOSED_SURFACES` environment variable. To expose companion tools directly in the advertised manifest, set `SNIPARA_EXPOSED_SURFACES=inline,companion` on the MCP server. This is optional: companion tools are still callable by name on demand via `snipara_help`, even if not advertised.
+The MCP server advertises different tool surfaces depending on the `SNIPARA_EXPOSED_SURFACES` environment variable. Hosted MCP defaults to inline tools plus a small companion maintenance set for index health, reindexing, and read-only memory hygiene. To expose all companion tools directly in the advertised manifest, set `SNIPARA_EXPOSED_SURFACES=inline,companion` on the MCP server. Remaining companion tools are discoverable via `snipara_help` and can be executed by direct JSON-RPC or clients/server configurations that expose those surfaces. Standard MCP agents only receive schemas for tools returned by `tools/list`.
 
 ## Installation
 
@@ -59,6 +59,17 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
+## New In 1.3.6
+
+- Adds `snipara-companion memory audit` for a read-only memory hygiene pass that
+  combines hosted memory health, cleanup candidates, and compaction dry-run.
+- Adds `memory health`, `memory clean-candidates`, and `memory compact` as
+  direct companion maintenance commands. `memory compact` always sends
+  `dry_run=true` and does not mutate memory.
+- Extends `memory-guard check` with `--intent`, `--destructive`, and
+  `--require-confirmation` so agents can surface memory/context contradictions
+  and ask the user before irreversible actions.
+
 ## New In 1.3.0
 
 - Adds top-level Git-style agent work commands: `status`, `brief`, `timeline`,
@@ -462,6 +473,10 @@ snipara-companion sync-documents --file ./snipara-business-context.json --dry-ru
 snipara-companion reindex --kind doc --mode incremental
 snipara-companion reindex --job-id index_job_123
 snipara-companion business-health --json
+snipara-companion memory audit --scope project --include-inactive
+snipara-companion memory health --scope project --json
+snipara-companion memory clean-candidates --scope project --limit-per-bucket 10
+snipara-companion memory compact --scope project --json
 snipara-companion chunk get --chunk-id chunk_123
 snipara-companion multi-query --queries "auth flow" "rate limiting"
 snipara-companion orchestrate --query "understand the auth architecture"
@@ -607,21 +622,27 @@ Semantics:
 - `snipara-companion sync-documents` = bulk `snipara_sync_documents` for text and supported binary parser documents from a JSON payload or directory
 - `snipara-companion sync-documents --dry-run` = validate the local payload and business-context freshness metadata without uploading
 - `snipara-companion business-health` = hosted `snipara_index_health`, with the `business_context` section surfaced for stale/reupload signals
+- `snipara-companion memory audit` = read-only memory hygiene pass that combines `snipara_memory_health`, `snipara_memory_clean_candidates`, and `snipara_memory_compact(dry_run=true)`
+- `snipara-companion memory health` = direct hosted `snipara_memory_health` diagnostics for active counts, stale/noise/anomaly samples, and auto-compaction threshold status
+- `snipara-companion memory clean-candidates` = direct hosted `snipara_memory_clean_candidates` review packet for noise, stale memories, duplicates, category anomalies, and human review queues
+- `snipara-companion memory compact` = hosted compaction preview only; it always calls `snipara_memory_compact` with `dry_run=true` and never mutates memory
 - `snipara-companion reindex` = trigger or poll hosted `snipara_reindex`; use after uploads when immediate chunk availability matters
 - `snipara-companion code *` = direct access to the code graph tools without routing through `snipara_context_query`
 - `snipara-companion recall` = direct durable memory lookup for decisions, learnings, preferences, and carryover
 - `snipara-companion session-bootstrap` = durable memory first, optional weak session carryover second
 - `snipara-companion task-commit` = durable task/phase/workflow outcomes only, not a mechanical mirror of every Git commit
 - `snipara-companion memory-guard check` = forced memory/context recall before retries, commits, or finalization when a command failed or a publishable package surface is touched
+- `snipara-companion memory-guard check --intent "<action>" --destructive --strict` = contradiction check before irreversible actions; blocks until the user explicitly confirms when memory/context disagrees or the action is destructive
 - `snipara-companion memory-guard remember --guard-tag pre-commit --text "..."` = create a project/team memory in a guard category such as `pre-commit`, `commit`, `failure`, `pre-final`, or `workflow-policy`
 - `--max-daily-tokens` is still accepted as a compatibility alias for `--max-context-tokens`
 
-### Memory Guard Before Commit
+### Memory Guard Before Commit Or Destructive Actions
 
 Memory Guard is deterministic, not a user preference. It detects two global signals:
 
 - failed or timed-out tool results emitted by Companion hooks
 - changed files under publishable npm or PyPI package manifests
+- explicit destructive or irreversible intent passed with `--intent` and `--destructive`
 
 When triggered, it recalls project guard memories by category and also queries source context before
 the agent retries, commits, or finalizes. Guard memories are just durable memories with a category tag:
@@ -636,8 +657,17 @@ Run the check manually with:
 
 ```bash
 snipara-companion memory-guard check --trigger pre-commit --staged --strict
+snipara-companion memory-guard check \
+  --intent "npm publish snipara-companion" \
+  --destructive \
+  --strict
 ```
 
+When memory or source context contradicts the requested action, the JSON output
+sets `requiresConfirmation=true`, includes `contradictions`, and provides a
+`confirmationPrompt`. In `--strict` mode the command exits non-zero until the
+operator has explicitly confirmed the override.
+
 ### Commit Memory Policy
 
 Companion separates two concepts:

package/dist/index.d.ts

@@ -997,17 +997,29 @@ interface ReleaseSurface {
     manifestPath: string;
 }
 interface MemoryGuardFinding {
-    code: "recent_failure" | "release_surface" | "manual";
+    code: "recent_failure" | "release_surface" | "manual" | "destructive_intent" | "contradiction";
     message: string;
 }
+interface MemoryGuardContradiction {
+    source: "memory" | "context";
+    reason: string;
+    excerpt: string;
+    memoryId?: string;
+    category?: string;
+    title?: string;
+    file?: string;
+}
 interface MemoryGuardCheckOptions {
     trigger?: MemoryGuardTrigger;
     files?: string[];
     staged?: boolean;
     command?: string;
+    intent?: string;
     result?: string;
     exitCode?: number;
     status?: string;
+    destructive?: boolean;
+    requireConfirmation?: boolean;
     strict?: boolean;
     json?: boolean;
     limit?: number;
@@ -1031,6 +1043,11 @@ interface MemoryGuardCheckResult {
     }>;
     query: string;
     categories: string[];
+    intent?: string;
+    destructive: boolean;
+    contradictions: MemoryGuardContradiction[];
+    requiresConfirmation: boolean;
+    confirmationPrompt?: string;
     memoryAvailable: boolean;
     contextAvailable: boolean;
     memories: RecalledMemory[];
@@ -1078,6 +1095,45 @@ interface ProjectIntelligenceBrief {
 declare function buildProjectIntelligenceBrief(options: ProjectIntelligenceBriefOptions): Promise<ProjectIntelligenceBrief>;
 declare function projectIntelligenceBriefCommand(options: ProjectIntelligenceBriefOptions): Promise<void>;
 
+interface MemoryHealthCommandOptions {
+    scope?: MemoryScope;
+    includeInactive?: boolean;
+    sampleLimit?: number;
+    json?: boolean;
+}
+interface MemoryCleanCandidatesCommandOptions {
+    scope?: MemoryScope;
+    includeInactive?: boolean;
+    limitPerBucket?: number;
+    json?: boolean;
+}
+interface MemoryCompactCommandOptions {
+    scope?: MemoryScope;
+    deduplicate?: boolean;
+    promoteThreshold?: number;
+    archiveOlderThanDays?: number;
+    json?: boolean;
+}
+interface MemoryAuditCommandOptions extends MemoryHealthCommandOptions, MemoryCleanCandidatesCommandOptions, MemoryCompactCommandOptions {
+}
+interface MemoryAuditResult {
+    version: "snipara.memory_audit.v1";
+    generatedAt: string;
+    scope?: MemoryScope;
+    health?: Record<string, unknown>;
+    cleanCandidates?: Record<string, unknown>;
+    compactDryRun?: Record<string, unknown>;
+    errors: Array<{
+        surface: string;
+        message: string;
+    }>;
+}
+declare function memoryHealthCommand(options: MemoryHealthCommandOptions): Promise<void>;
+declare function memoryCleanCandidatesCommand(options: MemoryCleanCandidatesCommandOptions): Promise<void>;
+declare function memoryCompactCommand(options: MemoryCompactCommandOptions): Promise<void>;
+declare function buildMemoryAudit(options: MemoryAuditCommandOptions): Promise<MemoryAuditResult>;
+declare function memoryAuditCommand(options: MemoryAuditCommandOptions): Promise<void>;
+
 interface VerifyCommandOptions {
     task?: string;
     qualifiedName?: string;
@@ -1994,4 +2050,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };