self-evolving-workflow 0.0.0-stage → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +90 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +479 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/common.d.ts +9 -0
  12. package/dist/common.js +42 -0
  13. package/dist/context-envelope.d.ts +59 -0
  14. package/dist/context-envelope.js +23 -0
  15. package/dist/host-adapters.d.ts +34 -0
  16. package/dist/host-adapters.js +151 -0
  17. package/dist/http.d.ts +3 -0
  18. package/dist/http.js +90 -0
  19. package/dist/index.d.ts +16 -0
  20. package/dist/index.js +13 -0
  21. package/dist/knowledge-cli.d.ts +183 -0
  22. package/dist/knowledge-cli.js +654 -0
  23. package/dist/knowledge-reads.d.ts +71 -0
  24. package/dist/knowledge-reads.js +193 -0
  25. package/dist/memory.d.ts +97 -0
  26. package/dist/memory.js +250 -0
  27. package/dist/retrospective.d.ts +57 -0
  28. package/dist/retrospective.js +248 -0
  29. package/dist/search.d.ts +36 -0
  30. package/dist/search.js +112 -0
  31. package/dist/skill-addition.d.ts +25 -0
  32. package/dist/skill-addition.js +89 -0
  33. package/dist/skill-design.d.ts +96 -0
  34. package/dist/skill-design.js +226 -0
  35. package/dist/skill-replay.d.ts +55 -0
  36. package/dist/skill-replay.js +451 -0
  37. package/dist/skill-route.d.ts +30 -0
  38. package/dist/skill-route.js +75 -0
  39. package/dist/transcript-evidence.d.ts +3 -0
  40. package/dist/transcript-evidence.js +58 -0
  41. package/dist/upstream/chunker.d.ts +24 -0
  42. package/dist/upstream/chunker.js +96 -0
  43. package/dist/upstream/file-protocol.d.ts +45 -0
  44. package/dist/upstream/file-protocol.js +117 -0
  45. package/dist/upstream/frontmatter.d.ts +47 -0
  46. package/dist/upstream/frontmatter.js +86 -0
  47. package/dist/upstream/graph-search.d.ts +33 -0
  48. package/dist/upstream/graph-search.js +67 -0
  49. package/dist/upstream/l1-extraction.d.ts +26 -0
  50. package/dist/upstream/l1-extraction.js +405 -0
  51. package/dist/upstream/llm.d.ts +8 -0
  52. package/dist/upstream/llm.js +1 -0
  53. package/dist/upstream/merge.d.ts +50 -0
  54. package/dist/upstream/merge.js +153 -0
  55. package/dist/upstream/prompts.d.ts +53 -0
  56. package/dist/upstream/prompts.js +185 -0
  57. package/dist/upstream/search-utils.d.ts +34 -0
  58. package/dist/upstream/search-utils.js +55 -0
  59. package/dist/upstream/slug.d.ts +26 -0
  60. package/dist/upstream/slug.js +103 -0
  61. package/dist/upstream/template.d.ts +29 -0
  62. package/dist/upstream/template.js +80 -0
  63. package/dist/upstream/tokenize.d.ts +4 -0
  64. package/dist/upstream/tokenize.js +29 -0
  65. package/dist/wiki-change.d.ts +76 -0
  66. package/dist/wiki-change.js +299 -0
  67. package/dist/wiki-entry.d.ts +26 -0
  68. package/dist/wiki-entry.js +93 -0
  69. package/dist/wiki-ingest.d.ts +12 -0
  70. package/dist/wiki-ingest.js +126 -0
  71. package/dist/wiki-migration.d.ts +16 -0
  72. package/dist/wiki-migration.js +268 -0
  73. package/dist/wiki-tokens.d.ts +1 -0
  74. package/dist/wiki-tokens.js +46 -0
  75. package/dist/wiki.d.ts +103 -0
  76. package/dist/wiki.js +330 -0
  77. package/dist/workflow-cli.d.ts +2 -0
  78. package/dist/workflow-cli.js +258 -0
  79. package/dist/workflow-install.d.ts +36 -0
  80. package/dist/workflow-install.js +148 -0
  81. package/dist/workflow-knowledge.d.ts +16 -0
  82. package/dist/workflow-knowledge.js +24 -0
  83. package/dist/workflow-mcp.d.ts +2 -0
  84. package/dist/workflow-mcp.js +144 -0
  85. package/dist/workflow-names.d.ts +4 -0
  86. package/dist/workflow-names.js +18 -0
  87. package/dist/workflow-runtime.d.ts +622 -0
  88. package/dist/workflow-runtime.js +627 -0
  89. package/dist/workflow-skills.d.ts +48 -0
  90. package/dist/workflow-skills.js +141 -0
  91. package/package.json +76 -4
  92. package/skills/ew-odyssey/SKILL.md +237 -0
  93. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  94. package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
  95. package/skills/ew-odyssey/references/odyssey-base.md +278 -0
  96. package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
  97. package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
  98. package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
  99. package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
  100. package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
  101. package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
  102. package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
  103. package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
  104. package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
  105. package/skills/ew-odyssey/references/odyssey-review.md +251 -0
  106. package/skills/ew-odyssey/references/odyssey-security.md +249 -0
  107. package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
  108. package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
  109. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
  110. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
  111. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
  112. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
  113. package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
  114. package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
  115. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
  116. package/skills/ew-orchestrate/SKILL.md +236 -0
  117. package/skills/ew-orchestrate/references/auto-policy.md +165 -0
  118. package/skills/ew-orchestrate/references/companion-route.md +52 -0
  119. package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
  120. package/skills/ew-orchestrate/references/goal.md +53 -0
  121. package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
  122. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
  123. package/skills/ew-orchestrate/references/planning.md +137 -0
  124. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
  125. package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
  126. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
  127. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
  128. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
  129. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
  130. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
  131. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
  132. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
  133. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
  134. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
  135. package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
  136. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
  137. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  138. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
  139. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
  140. package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
  141. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
  142. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
  143. package/skills/ew-skill-design/SKILL.md +28 -0
  144. package/skills/ew-skill-design/references/package-contract.md +28 -0
  145. package/skills/ew-skill-design/references/validation.md +7 -0
  146. package/skills/team-swarm/SKILL.md +231 -0
  147. package/skills/team-swarm/references/mcp-coordination.md +10 -0
  148. package/skills/team-swarm/roles/analyst/role.md +181 -0
  149. package/skills/team-swarm/roles/ant/role.md +149 -0
  150. package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
  151. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
  152. package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  153. package/skills/team-swarm/roles/coordinator/role.md +228 -0
  154. package/skills/team-swarm/roles/scorer/role.md +150 -0
  155. package/skills/team-swarm/scripts/aco.py +646 -0
  156. package/skills/team-swarm/scripts/pheromone.py +144 -0
  157. package/skills/team-swarm/scripts/scoring.py +111 -0
  158. package/skills/team-swarm/scripts/test_aco.py +606 -0
  159. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  160. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  161. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  162. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  163. package/skills/team-swarm/specs/swarm-protocol.md +123 -0
  164. package/skills/workflow-closeout/SKILL.md +10 -0
  165. package/skills/workflow-evolve/SKILL.md +79 -0
  166. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  167. package/skills/workflow-evolve/references/auto-loop.md +20 -0
  168. package/skills/workflow-evolve/references/history-review.md +14 -0
  169. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
  170. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  171. package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
  172. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  173. package/workflows/index.json +23 -0
@@ -0,0 +1,71 @@
1
+ export declare const KNOWLEDGE_READS_VERSION = "knowledge-reads/1.0";
2
+ export type KnowledgeSearchSource = 'code' | 'wiki' | 'wiki_references' | 'memory' | 'context';
3
+ export type KnowledgeReadKind = 'code' | 'wiki' | 'memory';
4
+ export interface KnowledgeSearchRecord {
5
+ search_id: string;
6
+ source: KnowledgeSearchSource;
7
+ query: string;
8
+ filters?: Record<string, unknown>;
9
+ returned_ids: string[];
10
+ total_hits: number;
11
+ }
12
+ export interface KnowledgeReadRecord {
13
+ kind: KnowledgeReadKind;
14
+ id: string;
15
+ from_search_id?: string;
16
+ content_sha256?: string;
17
+ version?: number;
18
+ }
19
+ export interface KnowledgeConstraintRecord {
20
+ knowledge_id: string;
21
+ content_sha256?: string;
22
+ scope: string[];
23
+ categories?: string[];
24
+ }
25
+ export interface KnowledgePriorReuse {
26
+ artifact_id: string;
27
+ producer_run_id: string;
28
+ content_sha256: string;
29
+ }
30
+ export interface KnowledgeReadsReceipt {
31
+ schema_version: typeof KNOWLEDGE_READS_VERSION;
32
+ searches: KnowledgeSearchRecord[];
33
+ reads: KnowledgeReadRecord[];
34
+ constraints_bound: KnowledgeConstraintRecord[];
35
+ priors_reuse?: KnowledgePriorReuse[];
36
+ }
37
+ export interface KnowledgeSearchInput {
38
+ source: KnowledgeSearchSource;
39
+ query: string;
40
+ filters?: Record<string, unknown>;
41
+ returnedIds: string[];
42
+ }
43
+ export interface KnowledgeReadInput {
44
+ kind: KnowledgeReadKind;
45
+ id: string;
46
+ fromSearchId?: string;
47
+ content?: string;
48
+ contentSha256?: string;
49
+ version?: number;
50
+ }
51
+ export interface KnowledgeConstraintInput {
52
+ knowledgeId: string;
53
+ scope: string[];
54
+ categories?: string[];
55
+ content?: string;
56
+ contentSha256?: string;
57
+ }
58
+ export declare function contentSha256(content: string): string;
59
+ export declare function validateKnowledgeReads(value: unknown): KnowledgeReadsReceipt;
60
+ export declare class KnowledgeReads {
61
+ private sequence;
62
+ private readonly searches;
63
+ private readonly reads;
64
+ private readonly constraints;
65
+ private readonly priorReuse?;
66
+ constructor(initial?: KnowledgeReadsReceipt);
67
+ recordSearch(input: KnowledgeSearchInput): string;
68
+ recordRead(input: KnowledgeReadInput): void;
69
+ bindConstraint(input: KnowledgeConstraintInput): void;
70
+ toJSON(): KnowledgeReadsReceipt;
71
+ }
@@ -0,0 +1,193 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { InputError, requireText } from './common.js';
3
+ export const KNOWLEDGE_READS_VERSION = 'knowledge-reads/1.0';
4
+ export function contentSha256(content) {
5
+ return `sha256:${createHash('sha256').update(content).digest('hex')}`;
6
+ }
7
+ function stringList(value, field) {
8
+ if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim())) {
9
+ throw new InputError(`Invalid knowledge read ${field}`);
10
+ }
11
+ return [...new Set(value.map(item => item.trim()))];
12
+ }
13
+ function optionalSha(value, field) {
14
+ if (value === undefined)
15
+ return undefined;
16
+ if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(value)) {
17
+ throw new InputError(`Invalid knowledge read ${field}`);
18
+ }
19
+ return value;
20
+ }
21
+ function record(value, field) {
22
+ if (!value || typeof value !== 'object' || Array.isArray(value))
23
+ throw new InputError(`Invalid knowledge read ${field}`);
24
+ return value;
25
+ }
26
+ function source(value, field) {
27
+ if (value !== 'code' && value !== 'wiki' && value !== 'wiki_references' && value !== 'memory' && value !== 'context') {
28
+ throw new InputError(`Invalid knowledge read ${field}`);
29
+ }
30
+ return value;
31
+ }
32
+ function kind(value, field) {
33
+ if (value !== 'code' && value !== 'wiki' && value !== 'memory')
34
+ throw new InputError(`Invalid knowledge read ${field}`);
35
+ return value;
36
+ }
37
+ function parseSearch(value, index) {
38
+ const item = record(value, `search ${index}`);
39
+ const total = item.total_hits;
40
+ if (!Number.isSafeInteger(total) || total < 0)
41
+ throw new InputError(`Invalid knowledge read search total ${index}`);
42
+ return {
43
+ search_id: requireText(item.search_id, `knowledge search ID ${index}`),
44
+ source: source(item.source, `search source ${index}`),
45
+ query: requireText(item.query, `knowledge search query ${index}`),
46
+ ...(item.filters === undefined ? {} : { filters: record(item.filters, `search filters ${index}`) }),
47
+ returned_ids: stringList(item.returned_ids, `search returned IDs ${index}`),
48
+ total_hits: total,
49
+ };
50
+ }
51
+ function parseRead(value, index) {
52
+ const item = record(value, `read ${index}`);
53
+ const version = item.version;
54
+ if (version !== undefined && (!Number.isSafeInteger(version) || version < 1)) {
55
+ throw new InputError(`Invalid knowledge read version ${index}`);
56
+ }
57
+ return {
58
+ kind: kind(item.kind, `read kind ${index}`),
59
+ id: requireText(item.id, `knowledge read ID ${index}`),
60
+ ...(item.from_search_id === undefined ? {} : { from_search_id: requireText(item.from_search_id, `knowledge read source ${index}`) }),
61
+ ...(item.content_sha256 === undefined ? {} : { content_sha256: optionalSha(item.content_sha256, `content hash ${index}`) }),
62
+ ...(version === undefined ? {} : { version: version }),
63
+ };
64
+ }
65
+ function parseConstraint(value, index) {
66
+ const item = record(value, `constraint ${index}`);
67
+ return {
68
+ knowledge_id: requireText(item.knowledge_id, `constraint ID ${index}`),
69
+ ...(item.content_sha256 === undefined ? {} : { content_sha256: optionalSha(item.content_sha256, `constraint hash ${index}`) }),
70
+ scope: stringList(item.scope, `constraint scope ${index}`),
71
+ ...(item.categories === undefined ? {} : { categories: stringList(item.categories, `constraint categories ${index}`) }),
72
+ };
73
+ }
74
+ function parsePriorReuse(value) {
75
+ const item = record(value, 'priors reuse');
76
+ const hash = optionalSha(item.content_sha256, 'priors content hash');
77
+ if (!hash)
78
+ throw new InputError('Missing priors content hash');
79
+ return {
80
+ artifact_id: requireText(item.artifact_id, 'priors artifact ID'),
81
+ producer_run_id: requireText(item.producer_run_id, 'priors producer Run ID'),
82
+ content_sha256: hash,
83
+ };
84
+ }
85
+ export function validateKnowledgeReads(value) {
86
+ const input = record(value, 'receipt');
87
+ if (input.schema_version !== KNOWLEDGE_READS_VERSION || !Array.isArray(input.searches) ||
88
+ !Array.isArray(input.reads) || !Array.isArray(input.constraints_bound)) {
89
+ throw new InputError('Invalid knowledge reads receipt');
90
+ }
91
+ const searches = input.searches.map(parseSearch);
92
+ const searchIds = new Set(searches.map(item => item.search_id));
93
+ if (searchIds.size !== searches.length)
94
+ throw new InputError('Duplicate knowledge search ID');
95
+ const reads = input.reads.map(parseRead);
96
+ for (const item of reads) {
97
+ if (item.from_search_id && !searchIds.has(item.from_search_id) && item.from_search_id !== 'priors') {
98
+ throw new InputError(`Unknown knowledge search ID: ${item.from_search_id}`);
99
+ }
100
+ }
101
+ if (input.priors_reuse !== undefined && !Array.isArray(input.priors_reuse))
102
+ throw new InputError('Invalid priors reuse receipt');
103
+ return {
104
+ schema_version: KNOWLEDGE_READS_VERSION,
105
+ searches,
106
+ reads,
107
+ constraints_bound: input.constraints_bound.map(parseConstraint),
108
+ ...(input.priors_reuse === undefined ? {} : { priors_reuse: input.priors_reuse.map(parsePriorReuse) }),
109
+ };
110
+ }
111
+ export class KnowledgeReads {
112
+ sequence = 0;
113
+ searches = [];
114
+ reads = [];
115
+ constraints = [];
116
+ priorReuse;
117
+ constructor(initial) {
118
+ if (!initial)
119
+ return;
120
+ const receipt = validateKnowledgeReads(initial);
121
+ this.searches.push(...receipt.searches);
122
+ this.reads.push(...receipt.reads);
123
+ this.constraints.push(...receipt.constraints_bound);
124
+ this.priorReuse = receipt.priors_reuse;
125
+ for (const search of this.searches) {
126
+ const match = /^search-(\d+)$/.exec(search.search_id);
127
+ if (match)
128
+ this.sequence = Math.max(this.sequence, Number(match[1]));
129
+ }
130
+ }
131
+ recordSearch(input) {
132
+ let searchId;
133
+ do {
134
+ searchId = `search-${++this.sequence}`;
135
+ } while (this.searches.some(search => search.search_id === searchId));
136
+ const query = requireText(input.query, 'knowledge search query');
137
+ const returnedIds = stringList(input.returnedIds, 'knowledge search returned IDs');
138
+ this.searches.push({
139
+ search_id: searchId,
140
+ source: input.source,
141
+ query,
142
+ ...(input.filters ? { filters: { ...input.filters } } : {}),
143
+ returned_ids: returnedIds,
144
+ total_hits: returnedIds.length,
145
+ });
146
+ return searchId;
147
+ }
148
+ recordRead(input) {
149
+ const id = requireText(input.id, 'knowledge read ID');
150
+ const fromSearchId = input.fromSearchId === undefined ? undefined : requireText(input.fromSearchId, 'knowledge read search ID');
151
+ if (fromSearchId && fromSearchId !== 'priors' && !this.searches.some(search => search.search_id === fromSearchId)) {
152
+ throw new InputError(`Unknown knowledge search ID: ${fromSearchId}`);
153
+ }
154
+ const contentHash = input.contentSha256 ?? (input.content === undefined ? undefined : contentSha256(input.content));
155
+ if (contentHash !== undefined)
156
+ optionalSha(contentHash, 'content hash');
157
+ if (input.version !== undefined && (!Number.isSafeInteger(input.version) || input.version < 1)) {
158
+ throw new InputError('Knowledge read version must be a positive integer');
159
+ }
160
+ if (this.reads.some(read => read.kind === input.kind && read.id === id && read.from_search_id === fromSearchId))
161
+ return;
162
+ this.reads.push({
163
+ kind: input.kind,
164
+ id,
165
+ ...(fromSearchId ? { from_search_id: fromSearchId } : {}),
166
+ ...(contentHash ? { content_sha256: contentHash } : {}),
167
+ ...(input.version === undefined ? {} : { version: input.version }),
168
+ });
169
+ }
170
+ bindConstraint(input) {
171
+ const id = requireText(input.knowledgeId, 'knowledge constraint ID');
172
+ const hash = input.contentSha256 ?? (input.content === undefined ? undefined : contentSha256(input.content));
173
+ if (hash !== undefined)
174
+ optionalSha(hash, 'constraint hash');
175
+ if (this.constraints.some(item => item.knowledge_id === id))
176
+ return;
177
+ this.constraints.push({
178
+ knowledge_id: id,
179
+ ...(hash ? { content_sha256: hash } : {}),
180
+ scope: stringList(input.scope, 'knowledge constraint scope'),
181
+ ...(input.categories ? { categories: stringList(input.categories, 'knowledge constraint categories') } : {}),
182
+ });
183
+ }
184
+ toJSON() {
185
+ return validateKnowledgeReads({
186
+ schema_version: KNOWLEDGE_READS_VERSION,
187
+ searches: this.searches,
188
+ reads: this.reads,
189
+ constraints_bound: this.constraints,
190
+ ...(this.priorReuse ? { priors_reuse: this.priorReuse } : {}),
191
+ });
192
+ }
193
+ }
@@ -0,0 +1,97 @@
1
+ import type { AgentMemoryPrompt } from './agent-memory-prompts.js';
2
+ import type { LlmClient } from './upstream/llm.js';
3
+ import type { KnowledgeReads } from './knowledge-reads.js';
4
+ export interface ConversationMessage {
5
+ id: string;
6
+ role: 'user' | 'assistant' | 'system' | 'tool';
7
+ timestamp: number | string;
8
+ content: string;
9
+ }
10
+ export interface MemoryInput {
11
+ id?: string;
12
+ content: string;
13
+ type?: string;
14
+ scene?: string;
15
+ session?: string;
16
+ priority?: number;
17
+ sourceMessageIds?: string[];
18
+ embedding?: ArrayLike<number>;
19
+ }
20
+ export interface MemoryRecord {
21
+ id: string;
22
+ content: string;
23
+ type: string;
24
+ scene: string;
25
+ session: string;
26
+ priority: number;
27
+ sourceMessageIds: string[];
28
+ createdAt: string;
29
+ updatedAt: string;
30
+ version: number;
31
+ }
32
+ export interface MemorySearchOptions {
33
+ limit?: number;
34
+ type?: string;
35
+ scene?: string;
36
+ session?: string;
37
+ embedding?: ArrayLike<number>;
38
+ }
39
+ export interface MemoryStoreOptions {
40
+ namespace?: string;
41
+ embed?: (text: string) => Promise<ArrayLike<number>>;
42
+ }
43
+ type Hit = MemoryRecord & {
44
+ score: number;
45
+ };
46
+ export declare class MemoryStore {
47
+ private readonly db;
48
+ private readonly namespace;
49
+ private readonly embed?;
50
+ constructor(path: string, options?: MemoryStoreOptions);
51
+ close(): void;
52
+ put(input: MemoryInput): Promise<MemoryRecord>;
53
+ putMany(inputs: MemoryInput[]): Promise<MemoryRecord[]>;
54
+ get(id: string, options?: {
55
+ knowledgeReads?: KnowledgeReads;
56
+ fromSearchId?: string;
57
+ }): MemoryRecord | undefined;
58
+ delete(id: string): boolean;
59
+ search(query: string, options?: MemorySearchOptions): Promise<{
60
+ strategy: "hybrid";
61
+ results: {
62
+ score: number;
63
+ id: string;
64
+ content: string;
65
+ type: string;
66
+ scene: string;
67
+ session: string;
68
+ priority: number;
69
+ sourceMessageIds: string[];
70
+ createdAt: string;
71
+ updatedAt: string;
72
+ version: number;
73
+ }[];
74
+ } | {
75
+ strategy: "embedding";
76
+ results: Hit[];
77
+ } | {
78
+ strategy: "fts";
79
+ results: Hit[];
80
+ }>;
81
+ extract(messages: ConversationMessage[], options: {
82
+ llm: LlmClient;
83
+ session: string;
84
+ mode?: 'chat' | 'code';
85
+ agentMemoryPrompt?: AgentMemoryPrompt;
86
+ systemPrompt?: string;
87
+ }): Promise<MemoryRecord[]>;
88
+ }
89
+ export declare function extractMemoryInputs(messages: ConversationMessage[], options: {
90
+ llm: LlmClient;
91
+ session: string;
92
+ mode?: 'chat' | 'code';
93
+ agentMemoryPrompt?: AgentMemoryPrompt;
94
+ systemPrompt?: string;
95
+ }): Promise<MemoryInput[]>;
96
+ export declare function validateConversationMessages(messages: readonly ConversationMessage[]): Set<string>;
97
+ export {};
package/dist/memory.js ADDED
@@ -0,0 +1,250 @@
1
+ import { createHash, randomUUID } from 'node:crypto';
2
+ import { mkdirSync } from 'node:fs';
3
+ import { dirname, resolve } from 'node:path';
4
+ import { InputError, openDb, requireText, searchLimit, transaction } from './common.js';
5
+ import { formatExtractionPrompt, getExtractMemoriesAgentPrompt } from './upstream/l1-extraction.js';
6
+ import { rrfMerge } from './upstream/search-utils.js';
7
+ import { bm25RankToScore, buildFtsQuery, tokenizeForFts } from './upstream/tokenize.js';
8
+ const recordFields = `m.id, m.content, m.type, m.scene, m.session, m.priority,
9
+ m.source_ids AS sourceMessageIds, m.created_at AS createdAt, m.updated_at AS updatedAt, m.version`;
10
+ function record(row) {
11
+ const { vector, sourceMessageIds, ...fields } = row;
12
+ return { ...fields, sourceMessageIds: JSON.parse(sourceMessageIds) };
13
+ }
14
+ function normalized(values) {
15
+ const vector = Array.from(values);
16
+ let scale = 0;
17
+ for (const value of vector) {
18
+ if (!Number.isFinite(value))
19
+ throw new InputError('embedding must contain finite numbers');
20
+ scale = Math.max(scale, Math.abs(value));
21
+ }
22
+ if (scale === 0) {
23
+ throw new InputError('embedding must be a non-zero vector of finite numbers');
24
+ }
25
+ const scaled = vector.map(value => value / scale);
26
+ const norm = Math.sqrt(scaled.reduce((sum, value) => sum + value ** 2, 0));
27
+ return scaled.map(value => value / norm);
28
+ }
29
+ export class MemoryStore {
30
+ db;
31
+ namespace;
32
+ embed;
33
+ constructor(path, options = {}) {
34
+ this.namespace = requireText(options.namespace ?? 'default', 'namespace');
35
+ this.embed = options.embed;
36
+ const file = path === ':memory:' ? path : resolve(path);
37
+ if (file !== ':memory:')
38
+ mkdirSync(dirname(file), { recursive: true });
39
+ this.db = openDb(file);
40
+ try {
41
+ this.db.exec(`
42
+ CREATE TABLE IF NOT EXISTS memory_records (
43
+ key INTEGER PRIMARY KEY,
44
+ namespace TEXT NOT NULL,
45
+ id TEXT NOT NULL,
46
+ content TEXT NOT NULL,
47
+ type TEXT NOT NULL,
48
+ scene TEXT NOT NULL,
49
+ session TEXT NOT NULL,
50
+ priority INTEGER NOT NULL,
51
+ source_ids TEXT NOT NULL,
52
+ created_at TEXT NOT NULL,
53
+ updated_at TEXT NOT NULL,
54
+ version INTEGER NOT NULL,
55
+ vector TEXT,
56
+ dimensions INTEGER,
57
+ UNIQUE (namespace, id)
58
+ );
59
+ CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(tokens, tokenize='unicode61');
60
+ `);
61
+ }
62
+ catch (error) {
63
+ this.db.close();
64
+ throw error;
65
+ }
66
+ }
67
+ close() {
68
+ this.db.close();
69
+ }
70
+ async put(input) {
71
+ return (await this.putMany([input]))[0];
72
+ }
73
+ async putMany(inputs) {
74
+ const prepared = await Promise.all(inputs.map(async (input) => {
75
+ const content = requireText(input.content, 'content');
76
+ const priority = input.priority ?? 50;
77
+ if (!Number.isInteger(priority) || priority < -1 || priority > 100) {
78
+ throw new InputError('priority must be an integer between -1 and 100');
79
+ }
80
+ const embedding = input.embedding ?? await this.embed?.(content);
81
+ return {
82
+ id: requireText(input.id ?? randomUUID(), 'id'), content, priority,
83
+ type: requireText(input.type ?? 'episodic', 'type'),
84
+ scene: input.scene ?? '', session: input.session ?? '',
85
+ sourceIds: JSON.stringify(input.sourceMessageIds ?? []),
86
+ vector: embedding === undefined ? null : normalized(embedding),
87
+ };
88
+ }));
89
+ const now = new Date().toISOString();
90
+ return transaction(this.db, () => prepared.map(input => {
91
+ const row = this.db.prepare(`
92
+ INSERT INTO memory_records (
93
+ namespace, id, content, type, scene, session, priority, source_ids, created_at, updated_at, version, vector, dimensions
94
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
95
+ ON CONFLICT (namespace, id) DO UPDATE SET
96
+ content=excluded.content, type=excluded.type, scene=excluded.scene, session=excluded.session,
97
+ priority=excluded.priority, source_ids=excluded.source_ids, updated_at=excluded.updated_at,
98
+ version=memory_records.version+1, vector=excluded.vector, dimensions=excluded.dimensions
99
+ WHERE (memory_records.content, memory_records.type, memory_records.scene, memory_records.session,
100
+ memory_records.priority, memory_records.source_ids, memory_records.vector)
101
+ IS NOT (excluded.content, excluded.type, excluded.scene, excluded.session,
102
+ excluded.priority, excluded.source_ids, excluded.vector)
103
+ RETURNING key
104
+ `).get(this.namespace, input.id, input.content, input.type, input.scene, input.session, input.priority, input.sourceIds, now, now, input.vector && JSON.stringify(input.vector), input.vector?.length ?? null);
105
+ if (row) {
106
+ const key = Number(row.key);
107
+ this.db.prepare('DELETE FROM memory_fts WHERE rowid = ?').run(key);
108
+ this.db.prepare('INSERT INTO memory_fts(rowid, tokens) VALUES (?, ?)').run(key, tokenizeForFts(input.content));
109
+ }
110
+ return this.get(input.id);
111
+ }));
112
+ }
113
+ get(id, options = {}) {
114
+ const row = this.db.prepare(`SELECT ${recordFields} FROM memory_records m WHERE namespace = ? AND id = ?`)
115
+ .get(this.namespace, id);
116
+ const result = row && record(row);
117
+ if (result && options.knowledgeReads) {
118
+ options.knowledgeReads.recordRead({
119
+ kind: 'memory', id: result.id, fromSearchId: options.fromSearchId,
120
+ content: result.content, version: result.version,
121
+ });
122
+ }
123
+ return result;
124
+ }
125
+ delete(id) {
126
+ return transaction(this.db, () => {
127
+ const row = this.db.prepare('DELETE FROM memory_records WHERE namespace = ? AND id = ? RETURNING key')
128
+ .get(this.namespace, id);
129
+ if (!row)
130
+ return false;
131
+ this.db.prepare('DELETE FROM memory_fts WHERE rowid = ?').run(Number(row.key));
132
+ return true;
133
+ });
134
+ }
135
+ async search(query, options = {}) {
136
+ const text = requireText(query, 'query');
137
+ const limit = searchLimit(options.limit);
138
+ const embedding = options.embedding ?? await this.embed?.(text);
139
+ const vector = embedding === undefined ? undefined : normalized(embedding);
140
+ const expression = buildFtsQuery(text);
141
+ const clauses = ['m.namespace = ?'];
142
+ const args = [this.namespace];
143
+ for (const field of ['type', 'scene', 'session']) {
144
+ if (options[field] !== undefined) {
145
+ clauses.push(`m.${field} = ?`);
146
+ args.push(options[field]);
147
+ }
148
+ }
149
+ const where = clauses.join(' AND ');
150
+ const candidates = vector ? limit * 3 : limit;
151
+ const keyword = expression ? this.db.prepare(`
152
+ SELECT ${recordFields}, bm25(memory_fts) AS rank FROM memory_fts
153
+ JOIN memory_records m ON m.key = memory_fts.rowid
154
+ WHERE memory_fts MATCH ? AND ${where} ORDER BY rank, m.id LIMIT ?
155
+ `).all(expression, ...args, candidates).map(({ rank, ...row }) => ({
156
+ ...record(row), score: bm25RankToScore(rank),
157
+ })) : [];
158
+ const semantic = [];
159
+ if (vector) {
160
+ const statement = this.db.prepare(`
161
+ SELECT ${recordFields}, m.vector FROM memory_records m WHERE ${where} AND m.dimensions = ? ORDER BY m.id
162
+ `);
163
+ for (const row of statement.iterate(...args, vector.length)) {
164
+ const other = JSON.parse(row.vector);
165
+ const score = vector.reduce((sum, value, i) => sum + value * other[i], 0);
166
+ if (score > 0)
167
+ semantic.push({ ...record(row), score });
168
+ }
169
+ semantic.sort((a, b) => b.score - a.score);
170
+ semantic.length = Math.min(candidates, semantic.length);
171
+ }
172
+ if (keyword.length && semantic.length) {
173
+ const results = rrfMerge([keyword, semantic], item => item.id)
174
+ .slice(0, limit).map(({ rrfScore, ...item }) => ({ ...item, score: rrfScore }));
175
+ return { strategy: 'hybrid', results };
176
+ }
177
+ if (semantic.length)
178
+ return { strategy: 'embedding', results: semantic.slice(0, limit) };
179
+ return { strategy: 'fts', results: keyword.slice(0, limit) };
180
+ }
181
+ async extract(messages, options) {
182
+ return this.putMany(await extractMemoryInputs(messages, options));
183
+ }
184
+ }
185
+ export async function extractMemoryInputs(messages, options) {
186
+ const session = requireText(options.session, 'session');
187
+ if (!messages.length)
188
+ return [];
189
+ const ids = validateConversationMessages(messages);
190
+ const agentMemoryPrompt = options.agentMemoryPrompt ?? getExtractMemoriesAgentPrompt(options.mode);
191
+ const raw = await options.llm.chat({
192
+ system: options.systemPrompt ?? agentMemoryPrompt.system,
193
+ prompt: formatExtractionPrompt({ newMessages: messages }),
194
+ label: agentMemoryPrompt.label,
195
+ });
196
+ return parseExtraction(raw, session, ids);
197
+ }
198
+ export function validateConversationMessages(messages) {
199
+ const ids = new Set();
200
+ for (const message of messages) {
201
+ const id = requireText(message?.id, 'message id');
202
+ if (ids.has(id))
203
+ throw new InputError(`Duplicate message id: ${id}`);
204
+ if (!['user', 'assistant', 'system', 'tool'].includes(message.role) ||
205
+ (typeof message.timestamp !== 'number' && typeof message.timestamp !== 'string') ||
206
+ !Number.isFinite(new Date(message.timestamp).getTime())) {
207
+ throw new InputError(`Invalid role or timestamp for message: ${id}`);
208
+ }
209
+ requireText(message.content, 'message content');
210
+ if (id !== message.id)
211
+ throw new InputError('message id cannot have surrounding whitespace');
212
+ ids.add(id);
213
+ }
214
+ return ids;
215
+ }
216
+ function object(value, label) {
217
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
218
+ throw new Error(`Invalid ${label} in memory extraction response`);
219
+ }
220
+ return value;
221
+ }
222
+ function parseExtraction(raw, session, messageIds) {
223
+ const text = raw.replace(/<think>[\s\S]*?<\/think>\s*/g, '').trim();
224
+ const json = text.match(/\[[\s\S]*\]/)?.[0];
225
+ if (!json)
226
+ throw new Error('Memory extraction response must contain a JSON array');
227
+ const scenes = JSON.parse(json);
228
+ if (!Array.isArray(scenes))
229
+ throw new Error('Memory extraction response must be an array');
230
+ return scenes.flatMap(value => {
231
+ const scene = object(value, 'scene');
232
+ if (!Array.isArray(scene.memories))
233
+ throw new Error('Memory extraction scene requires a memories array');
234
+ return scene.memories.map(value => {
235
+ const memory = object(value, 'memory');
236
+ const content = requireText(memory.content, 'memory content');
237
+ const type = requireText(memory.type ?? 'episodic', 'memory type');
238
+ const sourceIds = memory.source_message_ids ?? scene.message_ids;
239
+ const sourceMessageIds = Array.isArray(sourceIds)
240
+ ? [...new Set(sourceIds.map(String).filter(id => messageIds.has(id)))].sort()
241
+ : [];
242
+ const id = createHash('sha256').update(JSON.stringify([session, type, content, sourceMessageIds])).digest('hex');
243
+ return {
244
+ id, content, type, session, sourceMessageIds,
245
+ scene: typeof scene.scene_name === 'string' ? scene.scene_name : '',
246
+ priority: typeof memory.priority === 'number' ? memory.priority : undefined,
247
+ };
248
+ });
249
+ });
250
+ }
@@ -0,0 +1,57 @@
1
+ import { type ConversationMessage } from './memory.js';
2
+ import type { LlmClient } from './upstream/llm.js';
3
+ import type { Wiki } from './wiki.js';
4
+ import { type KnowledgeReadsReceipt } from './knowledge-reads.js';
5
+ export interface SkillSignal {
6
+ id: string;
7
+ kind: 'correction' | 'error' | 'retry' | 'aborted' | 'verified_fix' | 'workflow_issue' | 'unclassified';
8
+ summary: string;
9
+ sources: string[];
10
+ runIds: string[];
11
+ }
12
+ export interface ReviewedRun {
13
+ id: string;
14
+ command: string;
15
+ skillRef?: ReviewedSkillReference;
16
+ skillReads?: {
17
+ source: string;
18
+ files: Array<{
19
+ path: string;
20
+ sha256: string;
21
+ }>;
22
+ };
23
+ knowledgeReads?: {
24
+ source: string;
25
+ receipt: KnowledgeReadsReceipt;
26
+ };
27
+ retryOf?: string;
28
+ source: string;
29
+ }
30
+ interface ReviewedSkillReference {
31
+ skill_id: string;
32
+ commit: string;
33
+ tree: string;
34
+ package_path: string;
35
+ entry: string;
36
+ }
37
+ export declare function reviewSkillExecution(wiki: Wiki, project: string, execution: string, model: () => LlmClient): Promise<{
38
+ execution: string;
39
+ receipt: string;
40
+ skill: {
41
+ id: string;
42
+ version: string;
43
+ status: "failed" | "succeeded" | "cancelled";
44
+ };
45
+ evidence: number;
46
+ signals: SkillSignal[];
47
+ }>;
48
+ export declare function reviewSession(root: string, session: string, options: {
49
+ model: () => LlmClient;
50
+ transcript?: ConversationMessage[];
51
+ }): Promise<{
52
+ session: string;
53
+ evidence: number;
54
+ runs: ReviewedRun[];
55
+ signals: SkillSignal[];
56
+ }>;
57
+ export {};