Interface: MemoryHarnessContract

Defined in: memory-harness-contract.ts:20

Public programmatic contract of the Unified Memory Harness (MemoryHarness).

Methods

commit()

commit(input): Promise<{
  bucketStatusAfter:   | {
     bucketId: string;
     bucketRecordIds: string[];
     currentCount: number;
     hardCap: number | null;
     maxTotalRecords: number | null;
     maxTotalRecordsReached: boolean;
     softCap: number | null;
     totalRecordsCount: number;
     zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP";
   }
     | null;
  committedRecord:   | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "rule";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "lesson";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     lifecycle:   | {
        mode: "persistent";
      }
        | {
        mode: "read-count";
        remainingReads: number;
      }
        | {
        expiresAt: string;
        mode: "hard-expiry";
      }
        | {
        expiresAt: string;
        mode: "soft-expiry";
      };
     repos?: string[];
     role: string;
     text: string;
     type: "note";
     updatedAt?: string;
   }
     | null;
  gitCommitted: boolean;
  gitPushed: boolean;
  mergedKeepRecord:   | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "rule";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "lesson";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     lifecycle:   | {
        mode: "persistent";
      }
        | {
        mode: "read-count";
        remainingReads: number;
      }
        | {
        expiresAt: string;
        mode: "hard-expiry";
      }
        | {
        expiresAt: string;
        mode: "soft-expiry";
      };
     repos?: string[];
     role: string;
     text: string;
     type: "note";
     updatedAt?: string;
   }
     | null;
  op: "update" | "add" | "remove";
  previousRecord:   | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "rule";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     repos?: string[];
     role: string;
     text: string;
     type: "lesson";
     updatedAt?: string;
   }
     | {
     context?: string[];
     createdAt: string;
     id: string;
     lifecycle:   | {
        mode: "persistent";
      }
        | {
        mode: "read-count";
        remainingReads: number;
      }
        | {
        expiresAt: string;
        mode: "hard-expiry";
      }
        | {
        expiresAt: string;
        mode: "soft-expiry";
      };
     repos?: string[];
     role: string;
     text: string;
     type: "note";
     updatedAt?: string;
   }
     | null;
  removedIds: string[];
}>;

Defined in: memory-harness-contract.ts:71

Executes memory_commit to atomically add, update, or remove a record in memory.jsonl.

Parameters

Parameter	Type	Description
`input`	\| { `callerRole`: `string`; `capMerge?`: { `keepId`: `string`; `mergedText`: `string`; `removeId`: `string`; }; `context?`: `string`[]; `lifecycle?`: \| { `mode`: `"persistent"`; } \| { `mode`: `"read-count"`; `remainingReads`: `number`; } \| { `expiresAt`: `string`; `mode`: `"hard-expiry"`; } \| { `expiresAt`: `string`; `mode`: `"soft-expiry"`; }; `op`: `"add"`; `repos?`: `string`[]; `role`: `string`; `text`: `string`; `type`: `"rule"` \| `"lesson"` \| `"note"`; } \| { `alsoRemoveIds?`: `string`[]; `callerRole`: `string`; `context?`: `string`[] \| `null`; `id`: `string`; `lifecycle?`: \| { `mode`: `"persistent"`; } \| { `mode`: `"read-count"`; `remainingReads`: `number`; } \| { `expiresAt`: `string`; `mode`: `"hard-expiry"`; } \| { `expiresAt`: `string`; `mode`: `"soft-expiry"`; }; `op`: `"update"`; `repos?`: `string`[] \| `null`; `role?`: `string`; `text`: `string`; } \| { `callerRole`: `string`; `id`: `string`; `op`: `"remove"`; `reason`: \| `"owner_veto"` \| `"promoted_to_tier1_or_tier2"` \| `"merged_into_wider_record"` \| `"note_settled_or_obsolete"`; }	Discriminated `'add' \| 'update' \| 'remove'` mutation payload.

Returns

Promise<{ bucketStatusAfter: | { bucketId: string; bucketRecordIds: string[]; currentCount: number; hardCap: number | null; maxTotalRecords: number | null; maxTotalRecordsReached: boolean; softCap: number | null; totalRecordsCount: number; zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP"; } | null; committedRecord: | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "rule"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "lesson"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; lifecycle: | { mode: "persistent"; } | { mode: "read-count"; remainingReads: number; } | { expiresAt: string; mode: "hard-expiry"; } | { expiresAt: string; mode: "soft-expiry"; }; repos?: string[]; role: string; text: string; type: "note"; updatedAt?: string; } | null; gitCommitted: boolean; gitPushed: boolean; mergedKeepRecord: | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "rule"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "lesson"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; lifecycle: | { mode: "persistent"; } | { mode: "read-count"; remainingReads: number; } | { expiresAt: string; mode: "hard-expiry"; } | { expiresAt: string; mode: "soft-expiry"; }; repos?: string[]; role: string; text: string; type: "note"; updatedAt?: string; } | null; op: "update" | "add" | "remove"; previousRecord: | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "rule"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "lesson"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; lifecycle: | { mode: "persistent"; } | { mode: "read-count"; remainingReads: number; } | { expiresAt: string; mode: "hard-expiry"; } | { expiresAt: string; mode: "soft-expiry"; }; repos?: string[]; role: string; text: string; type: "note"; updatedAt?: string; } | null; removedIds: string[]; }>

Committed/previous record snapshots, post-commit bucket status, and Git sync flags.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', 'LESSON_FORMAT_INVALID', 'CAP_EXCEEDED', 'RECORD_NOT_FOUND', 'RULE_PROTECTION_VIOLATION', or 'GIT_SYNC_FAILED'.

drainNotes()

drainNotes(input): Promise<{
  drainedIds: string[];
  dryRun: boolean;
  gitCommitted: boolean;
  gitPushed: boolean;
  matchedNotes: object[];
}>;

Defined in: memory-harness-contract.ts:82

Executes memory_drain_notes in dry-run preview or destructive bulk-drain mode.

Parameters

Parameter	Type	Description
`input`	{ `callerRole`: `string`; `dryRun`: `boolean`; `ids?`: `string`[]; `modes`: (`"persistent"` \| `"read-count"` \| `"hard-expiry"` \| `"soft-expiry"` \| `"*"`)[]; `paths?`: `string`[]; `role?`: `string`; }	Lifecycle mode selectors, optional role/path/ID filters, and `dryRun` flag.
`input.callerRole?`	`string`	-
`input.dryRun?`	`boolean`	-
`input.ids?`	`string`[]	-
`input.modes?`	(`"persistent"` \| `"read-count"` \| `"hard-expiry"` \| `"soft-expiry"` \| `"*"`)[]	-
`input.paths?`	`string`[]	-
`input.role?`	`string`	-

Returns

Promise<{ drainedIds: string[]; dryRun: boolean; gitCommitted: boolean; gitPushed: boolean; matchedNotes: object[]; }>

Matched note records, drained IDs, and Git sync flags.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', or 'GIT_SYNC_FAILED'.

getConfig()

getConfig(): object;

Defined in: memory-harness-contract.ts:26

Returns the loaded and validated MemoryConfig for this workspace.

Returns

object

Validated unified memory configuration object.

Name	Type	Defined in
`allowedRoles`	`string`[]	schemas/memory-config.schema.ts:126
`caps`	`object`[]	schemas/memory-config.schema.ts:133
`distiller`	`object`	schemas/memory-config.schema.ts:168
`distiller.customInstructions?`	`string`	schemas/memory-config.schema.ts:101
`distiller.effort`	`"low"` \| `"medium"` \| `"high"`	schemas/memory-config.schema.ts:99
`distiller.model`	`string`	schemas/memory-config.schema.ts:98
`distiller.runner`	`"subagent"` \| `"claude-cli"`	schemas/memory-config.schema.ts:97
`distiller.timeoutMs`	`number`	schemas/memory-config.schema.ts:100
`format`	`object`	schemas/memory-config.schema.ts:156
`format.forbidRegexes`	`string`[]	schemas/memory-config.schema.ts:78
`format.maxChars`	`number`	schemas/memory-config.schema.ts:74
`format.requireSingleSentence`	`boolean`	schemas/memory-config.schema.ts:77
`format.requireSubstrings`	`string`[]	schemas/memory-config.schema.ts:76
`format.template`	`string`	schemas/memory-config.schema.ts:75
`maxTotalRecords?`	`number`	schemas/memory-config.schema.ts:132
`repoId`	`string`	schemas/memory-config.schema.ts:114
`storage`	`object`	schemas/memory-config.schema.ts:115
`storage.git`	`object`	schemas/memory-config.schema.ts:27
`storage.git.autoCommit`	`boolean`	schemas/memory-config.schema.ts:12
`storage.git.autoPullOnInit`	`boolean`	schemas/memory-config.schema.ts:14
`storage.git.autoPush`	`boolean`	schemas/memory-config.schema.ts:13
`storage.git.branch`	`string`	schemas/memory-config.schema.ts:11
`storage.git.checkoutDir`	`string`	schemas/memory-config.schema.ts:9
`storage.git.enabled`	`boolean`	schemas/memory-config.schema.ts:8
`storage.git.remoteUrl?`	`string`	schemas/memory-config.schema.ts:10
`storage.ledgerPath`	`string`	schemas/memory-config.schema.ts:26

handleFileInteractionHook()

handleFileInteractionHook(input): Promise<{
  compactionEpochId: string;
  formattedContext: string | null;
  injected: boolean;
  lessons: object[];
  notes: object[];
  rules: object[];
}>;

Defined in: memory-harness-contract.ts:93

Evaluates a file or directory tool interaction and returns unseen scoped memories for the active compaction epoch.

Parameters

Parameter	Type	Description
`input`	{ `role?`: `string`; `sessionId`: `string`; `touchedPaths`: `string`[]; `transcriptPath?`: `string`; }	Session ID, touched paths/globs, and optional role and transcript path.
`input.role?`	`string`	-
`input.sessionId?`	`string`	-
`input.touchedPaths?`	`string`[]	-
`input.transcriptPath?`	`string`	-

Returns

Promise<{ compactionEpochId: string; formattedContext: string | null; injected: boolean; lessons: object[]; notes: object[]; rules: object[]; }>

Injection status, compaction epoch ID, formatted context, and newly injected records.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', or 'GIT_SYNC_FAILED'.

init()

init(input): Promise<{
  lessons: object[];
  notes: object[];
  protocol: string;
  repoId: string;
  role: string;
  rules: object[];
}>;

Defined in: memory-harness-contract.ts:38

Executes memory_init at session start and after context compaction, returning the config-adapted protocol and all unscoped 'general' and <role> rules, lessons, and active notes.

Parameters

Parameter	Type	Description
`input`	{ `role`: `string`; `sessionId?`: `string`; }	Session role and optional session identifier.
`input.role?`	`string`	-
`input.sessionId?`	`string`	-

Returns

Promise<{ lessons: object[]; notes: object[]; protocol: string; repoId: string; role: string; rules: object[]; }>

Protocol markdown and ordered unscoped memories.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', or 'GIT_SYNC_FAILED'.

loadScoped()

loadScoped(input): Promise<{
  lessons: object[];
  normalizedPaths: string[];
  notes: object[];
  role: string;
  rules: object[];
}>;

Defined in: memory-harness-contract.ts:49

Executes memory_load_scoped for specific file paths, directories, or glob patterns.

Parameters

Parameter	Type	Description
`input`	{ `paths`: `string`[]; `role`: `string`; `sessionId?`: `string`; }	Target role, paths/globs to match, and optional session identifier.
`input.paths?`	`string`[]	-
`input.role?`	`string`	-
`input.sessionId?`	`string`	-

Returns

Promise<{ lessons: object[]; normalizedPaths: string[]; notes: object[]; role: string; rules: object[]; }>

Normalized query paths and matching scoped rules, lessons, and notes.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', or 'GIT_SYNC_FAILED'.

propose()

propose(input): Promise<
  | {
  bucketStatus: {
     bucketId: string;
     bucketRecordIds: string[];
     currentCount: number;
     hardCap: number | null;
     maxTotalRecords: number | null;
     maxTotalRecordsReached: boolean;
     softCap: number | null;
     totalRecordsCount: number;
     zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP";
  };
  choices: (
     | {
     alsoRemoveIds?: string[];
     existingRecord:   | {
        context?: string[];
        createdAt: string;
        id: string;
        repos?: string[];
        role: string;
        text: string;
        type: "rule";
        updatedAt?: string;
      }
        | {
        context?: string[];
        createdAt: string;
        id: string;
        repos?: string[];
        role: string;
        text: string;
        type: "lesson";
        updatedAt?: string;
      };
     op: "update";
     proposedContext?: string[] | null;
     proposedRepos?: string[] | null;
     proposedRole: string;
     proposedText: string;
     targetId: string;
     whyMatched: string;
   }
     | {
     capMerge?: {
        keepId: string;
        mergedText: string;
        removeId: string;
        whyMerged: string;
     };
     op: "add";
     proposedContext?: string[];
     proposedRepos?: string[];
     proposedRole: string;
     proposedText: string;
  })[];
  executionMode: "resolved";
  matchStatus:   | "NO_MATCH"
     | "LIKELY_MATCH"
     | "EXACT_DUPLICATE"
     | "REJECTED_TIER_1_OR_2";
  recommendedChoiceIndex: number;
  requiresOwnerGo: boolean;
  tierRejectionReason?: string;
  type: "rule" | "lesson";
}
  | {
  bucketStatus: {
     bucketId: string;
     bucketRecordIds: string[];
     currentCount: number;
     hardCap: number | null;
     maxTotalRecords: number | null;
     maxTotalRecordsReached: boolean;
     softCap: number | null;
     totalRecordsCount: number;
     zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP";
  };
  delegateToSubagent: {
     effort: "low" | "medium" | "high";
     model: string;
     outputJsonSchema: Record<string, unknown>;
     systemPrompt: string;
     timeoutMs: number;
     userPrompt: string;
  };
  executionMode: "delegate_to_subagent";
  requiresOwnerGo: boolean;
  type: "rule" | "lesson";
}>;

Defined in: memory-harness-contract.ts:60

Executes memory_propose to format, deduplicate, and evaluate capacity for a rule or lesson candidate.

Parameters

Parameter	Type	Description
`input`	{ `callerRole`: `string`; `context?`: `string`[]; `incident?`: `string`; `rawText`: `string`; `repos?`: `string`[]; `targetRole`: `string`; `type`: `"rule"` \| `"lesson"`; }	Candidate rule or lesson payload and optional scope/incident context.
`input.callerRole?`	`string`	-
`input.context?`	`string`[]	-
`input.incident?`	`string`	-
`input.rawText?`	`string`	-
`input.repos?`	`string`[]	-
`input.targetRole?`	`string`	-
`input.type?`	`"rule"` \| `"lesson"`	-

Returns

Promise< | { bucketStatus: { bucketId: string; bucketRecordIds: string[]; currentCount: number; hardCap: number | null; maxTotalRecords: number | null; maxTotalRecordsReached: boolean; softCap: number | null; totalRecordsCount: number; zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP"; }; choices: ( | { alsoRemoveIds?: string[]; existingRecord: | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "rule"; updatedAt?: string; } | { context?: string[]; createdAt: string; id: string; repos?: string[]; role: string; text: string; type: "lesson"; updatedAt?: string; }; op: "update"; proposedContext?: string[] | null; proposedRepos?: string[] | null; proposedRole: string; proposedText: string; targetId: string; whyMatched: string; } | { capMerge?: { keepId: string; mergedText: string; removeId: string; whyMerged: string; }; op: "add"; proposedContext?: string[]; proposedRepos?: string[]; proposedRole: string; proposedText: string; })[]; executionMode: "resolved"; matchStatus: | "NO_MATCH" | "LIKELY_MATCH" | "EXACT_DUPLICATE" | "REJECTED_TIER_1_OR_2"; recommendedChoiceIndex: number; requiresOwnerGo: boolean; tierRejectionReason?: string; type: "rule" | "lesson"; } | { bucketStatus: { bucketId: string; bucketRecordIds: string[]; currentCount: number; hardCap: number | null; maxTotalRecords: number | null; maxTotalRecordsReached: boolean; softCap: number | null; totalRecordsCount: number; zone: "UNCAPPED" | "UNDER_SOFT_CAP" | "SOFT_CAP_PRESSURE" | "AT_HARD_CAP"; }; delegateToSubagent: { effort: "low" | "medium" | "high"; model: string; outputJsonSchema: Record<string, unknown>; systemPrompt: string; timeoutMs: number; userPrompt: string; }; executionMode: "delegate_to_subagent"; requiresOwnerGo: boolean; type: "rule" | "lesson"; }>

Resolved Distiller proposal choices or subagent delegation payload.

Throws

With 'INVALID_ROLE', 'VALIDATION_FAILED', 'LESSON_FORMAT_INVALID', 'RULE_PROTECTION_VIOLATION', 'DISTILLER_EXECUTION_FAILED', or 'GIT_SYNC_FAILED'.

Interface: MemoryHarnessContract ​

Methods ​

commit() ​

Parameters ​

Returns ​

Throws ​

drainNotes() ​

Parameters ​

Returns ​

Throws ​

getConfig() ​

Returns ​

handleFileInteractionHook() ​

Parameters ​

Returns ​

Throws ​

init() ​

Parameters ​

Returns ​

Throws ​

loadScoped() ​

Parameters ​

Returns ​

Throws ​

propose() ​

Parameters ​

Returns ​

Throws ​

Interface: MemoryHarnessContract

Methods

commit()

Parameters

Returns

Throws

drainNotes()

Parameters

Returns

Throws

getConfig()

Returns

handleFileInteractionHook()

Parameters

Returns

Throws

init()

Parameters

Returns

Throws

loadScoped()

Parameters

Returns

Throws

propose()

Parameters

Returns

Throws