snipara-companion 1.1.21 → 1.1.23

package/README.md

@@ -448,9 +448,46 @@ Semantics:
 - `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 outcomes only
+- `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 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 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
+
+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:
+
+```bash
+snipara-companion memory-guard remember \
+  --guard-tag pre-commit \
+  --text "For npm packages, run npm login --auth-type=web in a TTY, publish, then verify dist-tags and npx help."
+```
+
+Run the check manually with:
+
+```bash
+snipara-companion memory-guard check --trigger pre-commit --staged --strict
+```
+
+### Commit Memory Policy
+
+Companion separates two concepts:
+
+- `git commit` is a version-control checkpoint.
+- `snipara-companion task-commit`, `workflow phase-commit`, and `final-commit` call hosted
+  `snipara_end_of_task_commit` to persist meaningful task, phase, or workflow outcomes.
+
+Do not call `snipara_end_of_task_commit` mechanically for every Git commit. For risky commits,
+package releases, or retries after failures, run Memory Guard first so the agent sees relevant
+project memory and context. If a team wants automatic lightweight checkpoints for every Git commit,
+keep that in a separate hook or adapter; reserve `task-commit` for durable summaries worth recalling.
+
 ### Compaction-Safe LLM Plan Workflow
 
 Use this when the user's LLM has already produced a plan and Snipara should enforce the workflow around it. For coding work, choose LITE, STANDARD, FULL, or FULL + ORCHESTRATED explicitly before editing: LITE is for small single-phase changes, STANDARD is for normal context/code-graph work, FULL managed workflow is for multi-file, risky, release/deploy, architectural, compaction-prone, or maintainer-sensitive work, and FULL + ORCHESTRATED is for production proof gates, drift checks, htasks, or explicit multi-agent coordination.

package/dist/index.d.ts

@@ -318,6 +318,12 @@ interface MemoriesResult {
     total_count: number;
     has_more: boolean;
 }
+interface RememberMemoryResult {
+    memory_id?: string;
+    stored?: boolean;
+    message?: string;
+    [key: string]: unknown;
+}
 interface MemoryInvalidateResult {
     memory_id: string;
     status: MemoryStatus;
@@ -527,6 +533,14 @@ declare class RLMClient {
         includeInactive?: boolean;
         warningThreshold?: number;
     }): Promise<RecallResult>;
+    rememberMemory(args: {
+        text: string;
+        type?: MemoryType;
+        scope?: MemoryScope;
+        category?: string;
+        ttlDays?: number;
+        source?: string;
+    }): Promise<RememberMemoryResult>;
     /**
      * List stored memories with lifecycle filters.
      */
@@ -652,6 +666,65 @@ declare function buildToolResultPayload(options: ToolResultPayloadOptions): Reco
 declare function getStuckGuardInjection(decision: StuckGuardDecision): string | null;
 declare function formatStuckGuardDecision(result: StuckGuardEvaluationResult): string;
 
+type MemoryGuardTrigger = "failure" | "pre-commit" | "commit" | "pre-final" | "manual";
+interface ReleaseSurface {
+    ecosystem: "npm" | "pypi";
+    name: string;
+    version?: string;
+    manifestPath: string;
+}
+interface MemoryGuardFinding {
+    code: "recent_failure" | "release_surface" | "manual";
+    message: string;
+}
+interface MemoryGuardCheckOptions {
+    trigger?: MemoryGuardTrigger;
+    files?: string[];
+    staged?: boolean;
+    command?: string;
+    result?: string;
+    exitCode?: number;
+    status?: string;
+    strict?: boolean;
+    json?: boolean;
+    limit?: number;
+    categories?: string[];
+    includeContext?: boolean;
+    recentFailures?: boolean;
+}
+interface MemoryGuardCheckResult {
+    triggered: boolean;
+    shouldBlock: boolean;
+    trigger: MemoryGuardTrigger;
+    findings: MemoryGuardFinding[];
+    files: string[];
+    releaseSurfaces: ReleaseSurface[];
+    recentFailures: Array<{
+        createdAt: string;
+        command?: string;
+        classification?: string;
+        exitCode?: number;
+        status?: string;
+    }>;
+    query: string;
+    categories: string[];
+    memoryAvailable: boolean;
+    contextAvailable: boolean;
+    memories: RecalledMemory[];
+    contextSections: Array<{
+        title: string;
+        file: string;
+        relevanceScore: number;
+        preview: string;
+    }>;
+    warnings: string[];
+}
+declare function normalizeGuardTag(tag: string): string;
+declare function categoryFromGuardTag(tag: string): string;
+declare function detectReleaseSurfacesFromFiles(root: string, files: string[]): ReleaseSurface[];
+declare function getStagedFiles(root: string): string[];
+declare function runMemoryGuardCheck(options?: MemoryGuardCheckOptions): Promise<MemoryGuardCheckResult>;
+
 type SyncDocumentKind = "DOC" | "BINARY";
 type OnboardFolderMode = "auto" | "business_context" | "code_project" | "mixed";
 type DetectedOnboardFolderMode = "business_context" | "code_project" | "mixed" | "unknown";
@@ -965,4 +1038,4 @@ declare function loadTeamSyncState(rootDir?: string): TeamSyncState;
 declare function saveTeamSyncState(state: TeamSyncState, rootDir?: string): void;
 declare function getTeamSyncStatePath(rootDir?: string): string;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_STATE_RELATIVE_PATH, buildAutomationInstallPlan, buildCanonicalEvent, buildOnboardFolderManifest, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildWorkflowPhaseCommitSummary, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, extractCommandFromToolInput, extractFilesFromToolInput, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getPlanStepDisplayTitle, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, normalizeWorkflowPlanInput, resolveQueryFromToolInput, saveConfig, saveTeamSyncState };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_STATE_RELATIVE_PATH, buildAutomationInstallPlan, buildCanonicalEvent, buildOnboardFolderManifest, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildWorkflowPhaseCommitSummary, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, extractCommandFromToolInput, extractFilesFromToolInput, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, normalizeGuardTag, normalizeWorkflowPlanInput, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState };