@claude-flow/memory 3.0.0-alpha.2 → 3.0.0-alpha.20

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 (253) hide show
  1. package/README.md +858 -249
  2. package/dist/agent-memory-scope.d.ts +131 -0
  3. package/dist/agent-memory-scope.d.ts.map +1 -0
  4. package/dist/agent-memory-scope.js +223 -0
  5. package/dist/agent-memory-scope.js.map +1 -0
  6. package/dist/agent-memory-scope.test.d.ts +8 -0
  7. package/dist/agent-memory-scope.test.d.ts.map +1 -0
  8. package/dist/agent-memory-scope.test.js +463 -0
  9. package/dist/agent-memory-scope.test.js.map +1 -0
  10. package/dist/agentdb-adapter.d.ts +82 -4
  11. package/dist/agentdb-adapter.d.ts.map +1 -1
  12. package/dist/agentdb-adapter.js +388 -17
  13. package/dist/agentdb-adapter.js.map +1 -1
  14. package/dist/agentdb-backend.d.ts +6 -0
  15. package/dist/agentdb-backend.d.ts.map +1 -1
  16. package/dist/agentdb-backend.js +115 -51
  17. package/dist/agentdb-backend.js.map +1 -1
  18. package/dist/auto-memory-bridge.d.ts +237 -0
  19. package/dist/auto-memory-bridge.d.ts.map +1 -0
  20. package/dist/auto-memory-bridge.js +758 -0
  21. package/dist/auto-memory-bridge.js.map +1 -0
  22. package/dist/auto-memory-bridge.test.d.ts +8 -0
  23. package/dist/auto-memory-bridge.test.d.ts.map +1 -0
  24. package/dist/auto-memory-bridge.test.js +849 -0
  25. package/dist/auto-memory-bridge.test.js.map +1 -0
  26. package/dist/benchmark.test.d.ts +2 -0
  27. package/dist/benchmark.test.d.ts.map +1 -0
  28. package/dist/benchmark.test.js +277 -0
  29. package/dist/benchmark.test.js.map +1 -0
  30. package/dist/consolidator.d.ts +96 -0
  31. package/dist/consolidator.d.ts.map +1 -0
  32. package/dist/consolidator.js +209 -0
  33. package/dist/consolidator.js.map +1 -0
  34. package/dist/consolidator.test.d.ts +17 -0
  35. package/dist/consolidator.test.d.ts.map +1 -0
  36. package/dist/consolidator.test.js +239 -0
  37. package/dist/consolidator.test.js.map +1 -0
  38. package/dist/controller-registry.d.ts +232 -0
  39. package/dist/controller-registry.d.ts.map +1 -0
  40. package/dist/controller-registry.js +1049 -0
  41. package/dist/controller-registry.js.map +1 -0
  42. package/dist/controller-registry.test.d.ts +14 -0
  43. package/dist/controller-registry.test.d.ts.map +1 -0
  44. package/dist/controller-registry.test.js +691 -0
  45. package/dist/controller-registry.test.js.map +1 -0
  46. package/dist/database-provider.d.ts +14 -2
  47. package/dist/database-provider.d.ts.map +1 -1
  48. package/dist/database-provider.js +63 -3
  49. package/dist/database-provider.js.map +1 -1
  50. package/dist/database-provider.test.js +56 -3
  51. package/dist/database-provider.test.js.map +1 -1
  52. package/dist/entity-tagger.d.ts +31 -0
  53. package/dist/entity-tagger.d.ts.map +1 -0
  54. package/dist/entity-tagger.js +80 -0
  55. package/dist/entity-tagger.js.map +1 -0
  56. package/dist/entity-tagger.test.d.ts +12 -0
  57. package/dist/entity-tagger.test.d.ts.map +1 -0
  58. package/dist/entity-tagger.test.js +70 -0
  59. package/dist/entity-tagger.test.js.map +1 -0
  60. package/dist/fts5.test.d.ts +13 -0
  61. package/dist/fts5.test.d.ts.map +1 -0
  62. package/dist/fts5.test.js +144 -0
  63. package/dist/fts5.test.js.map +1 -0
  64. package/dist/graceful-retrieval.test.d.ts +14 -0
  65. package/dist/graceful-retrieval.test.d.ts.map +1 -0
  66. package/dist/graceful-retrieval.test.js +192 -0
  67. package/dist/graceful-retrieval.test.js.map +1 -0
  68. package/dist/hnsw-index.d.ts +51 -0
  69. package/dist/hnsw-index.d.ts.map +1 -1
  70. package/dist/hnsw-index.js +396 -12
  71. package/dist/hnsw-index.js.map +1 -1
  72. package/dist/hnsw-persistence.test.d.ts +13 -0
  73. package/dist/hnsw-persistence.test.d.ts.map +1 -0
  74. package/dist/hnsw-persistence.test.js +208 -0
  75. package/dist/hnsw-persistence.test.js.map +1 -0
  76. package/dist/hybrid-backend.d.ts +28 -0
  77. package/dist/hybrid-backend.d.ts.map +1 -1
  78. package/dist/hybrid-backend.js +82 -4
  79. package/dist/hybrid-backend.js.map +1 -1
  80. package/dist/hybrid-backend.test.js +6 -5
  81. package/dist/hybrid-backend.test.js.map +1 -1
  82. package/dist/index.d.ts +167 -9
  83. package/dist/index.d.ts.map +1 -1
  84. package/dist/index.js +277 -30
  85. package/dist/index.js.map +1 -1
  86. package/dist/index.test.d.ts +10 -0
  87. package/dist/index.test.d.ts.map +1 -0
  88. package/dist/index.test.js +71 -0
  89. package/dist/index.test.js.map +1 -0
  90. package/dist/json-security.d.ts +12 -0
  91. package/dist/json-security.d.ts.map +1 -0
  92. package/dist/json-security.js +20 -0
  93. package/dist/json-security.js.map +1 -0
  94. package/dist/learning-bridge.d.ts +137 -0
  95. package/dist/learning-bridge.d.ts.map +1 -0
  96. package/dist/learning-bridge.js +335 -0
  97. package/dist/learning-bridge.js.map +1 -0
  98. package/dist/learning-bridge.test.d.ts +8 -0
  99. package/dist/learning-bridge.test.d.ts.map +1 -0
  100. package/dist/learning-bridge.test.js +578 -0
  101. package/dist/learning-bridge.test.js.map +1 -0
  102. package/dist/memory-graph.d.ts +100 -0
  103. package/dist/memory-graph.d.ts.map +1 -0
  104. package/dist/memory-graph.js +333 -0
  105. package/dist/memory-graph.js.map +1 -0
  106. package/dist/memory-graph.test.d.ts +8 -0
  107. package/dist/memory-graph.test.d.ts.map +1 -0
  108. package/dist/memory-graph.test.js +609 -0
  109. package/dist/memory-graph.test.js.map +1 -0
  110. package/dist/persistent-sona.d.ts +144 -0
  111. package/dist/persistent-sona.d.ts.map +1 -0
  112. package/dist/persistent-sona.js +332 -0
  113. package/dist/persistent-sona.js.map +1 -0
  114. package/dist/rvf-backend.d.ts +53 -0
  115. package/dist/rvf-backend.d.ts.map +1 -0
  116. package/dist/rvf-backend.js +643 -0
  117. package/dist/rvf-backend.js.map +1 -0
  118. package/dist/rvf-learning-store.d.ts +139 -0
  119. package/dist/rvf-learning-store.d.ts.map +1 -0
  120. package/dist/rvf-learning-store.js +295 -0
  121. package/dist/rvf-learning-store.js.map +1 -0
  122. package/dist/rvf-migration.d.ts +45 -0
  123. package/dist/rvf-migration.d.ts.map +1 -0
  124. package/dist/rvf-migration.js +254 -0
  125. package/dist/rvf-migration.js.map +1 -0
  126. package/dist/smart-retrieval.d.ts +118 -0
  127. package/dist/smart-retrieval.d.ts.map +1 -0
  128. package/dist/smart-retrieval.js +322 -0
  129. package/dist/smart-retrieval.js.map +1 -0
  130. package/dist/smart-retrieval.test.d.ts +2 -0
  131. package/dist/smart-retrieval.test.d.ts.map +1 -0
  132. package/dist/smart-retrieval.test.js +238 -0
  133. package/dist/smart-retrieval.test.js.map +1 -0
  134. package/dist/sqlite-backend.d.ts +10 -0
  135. package/dist/sqlite-backend.d.ts.map +1 -1
  136. package/dist/sqlite-backend.js +170 -74
  137. package/dist/sqlite-backend.js.map +1 -1
  138. package/dist/sqljs-backend.d.ts +9 -0
  139. package/dist/sqljs-backend.d.ts.map +1 -1
  140. package/dist/sqljs-backend.js +120 -29
  141. package/dist/sqljs-backend.js.map +1 -1
  142. package/dist/types.d.ts +3 -0
  143. package/dist/types.d.ts.map +1 -1
  144. package/package.json +48 -35
  145. package/.agentic-flow/intelligence.json +0 -16
  146. package/__tests__/coverage/base.css +0 -224
  147. package/__tests__/coverage/block-navigation.js +0 -87
  148. package/__tests__/coverage/coverage-final.json +0 -19
  149. package/__tests__/coverage/favicon.png +0 -0
  150. package/__tests__/coverage/index.html +0 -206
  151. package/__tests__/coverage/lcov-report/base.css +0 -224
  152. package/__tests__/coverage/lcov-report/block-navigation.js +0 -87
  153. package/__tests__/coverage/lcov-report/favicon.png +0 -0
  154. package/__tests__/coverage/lcov-report/index.html +0 -206
  155. package/__tests__/coverage/lcov-report/prettify.css +0 -1
  156. package/__tests__/coverage/lcov-report/prettify.js +0 -2
  157. package/__tests__/coverage/lcov-report/sort-arrow-sprite.png +0 -0
  158. package/__tests__/coverage/lcov-report/sorter.js +0 -210
  159. package/__tests__/coverage/lcov-report/src/agentdb-adapter.ts.html +0 -2737
  160. package/__tests__/coverage/lcov-report/src/agentdb-backend.ts.html +0 -3130
  161. package/__tests__/coverage/lcov-report/src/application/commands/delete-memory.command.ts.html +0 -601
  162. package/__tests__/coverage/lcov-report/src/application/commands/index.html +0 -131
  163. package/__tests__/coverage/lcov-report/src/application/commands/store-memory.command.ts.html +0 -394
  164. package/__tests__/coverage/lcov-report/src/application/queries/index.html +0 -116
  165. package/__tests__/coverage/lcov-report/src/application/queries/search-memory.query.ts.html +0 -796
  166. package/__tests__/coverage/lcov-report/src/application/services/index.html +0 -116
  167. package/__tests__/coverage/lcov-report/src/application/services/memory-application-service.ts.html +0 -793
  168. package/__tests__/coverage/lcov-report/src/cache-manager.ts.html +0 -1633
  169. package/__tests__/coverage/lcov-report/src/database-provider.ts.html +0 -1618
  170. package/__tests__/coverage/lcov-report/src/domain/entities/index.html +0 -116
  171. package/__tests__/coverage/lcov-report/src/domain/entities/memory-entry.ts.html +0 -952
  172. package/__tests__/coverage/lcov-report/src/domain/services/index.html +0 -116
  173. package/__tests__/coverage/lcov-report/src/domain/services/memory-domain-service.ts.html +0 -1294
  174. package/__tests__/coverage/lcov-report/src/hnsw-index.ts.html +0 -3124
  175. package/__tests__/coverage/lcov-report/src/hybrid-backend.ts.html +0 -2167
  176. package/__tests__/coverage/lcov-report/src/index.html +0 -266
  177. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/hybrid-memory-repository.ts.html +0 -1633
  178. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/index.html +0 -116
  179. package/__tests__/coverage/lcov-report/src/migration.ts.html +0 -2092
  180. package/__tests__/coverage/lcov-report/src/query-builder.ts.html +0 -1711
  181. package/__tests__/coverage/lcov-report/src/sqlite-backend.ts.html +0 -2281
  182. package/__tests__/coverage/lcov-report/src/sqljs-backend.ts.html +0 -2374
  183. package/__tests__/coverage/lcov-report/src/types.ts.html +0 -2266
  184. package/__tests__/coverage/lcov.info +0 -10238
  185. package/__tests__/coverage/prettify.css +0 -1
  186. package/__tests__/coverage/prettify.js +0 -2
  187. package/__tests__/coverage/sort-arrow-sprite.png +0 -0
  188. package/__tests__/coverage/sorter.js +0 -210
  189. package/__tests__/coverage/src/agentdb-adapter.ts.html +0 -2737
  190. package/__tests__/coverage/src/agentdb-backend.ts.html +0 -3130
  191. package/__tests__/coverage/src/application/commands/delete-memory.command.ts.html +0 -601
  192. package/__tests__/coverage/src/application/commands/index.html +0 -131
  193. package/__tests__/coverage/src/application/commands/store-memory.command.ts.html +0 -394
  194. package/__tests__/coverage/src/application/queries/index.html +0 -116
  195. package/__tests__/coverage/src/application/queries/search-memory.query.ts.html +0 -796
  196. package/__tests__/coverage/src/application/services/index.html +0 -116
  197. package/__tests__/coverage/src/application/services/memory-application-service.ts.html +0 -793
  198. package/__tests__/coverage/src/cache-manager.ts.html +0 -1633
  199. package/__tests__/coverage/src/database-provider.ts.html +0 -1618
  200. package/__tests__/coverage/src/domain/entities/index.html +0 -116
  201. package/__tests__/coverage/src/domain/entities/memory-entry.ts.html +0 -952
  202. package/__tests__/coverage/src/domain/services/index.html +0 -116
  203. package/__tests__/coverage/src/domain/services/memory-domain-service.ts.html +0 -1294
  204. package/__tests__/coverage/src/hnsw-index.ts.html +0 -3124
  205. package/__tests__/coverage/src/hybrid-backend.ts.html +0 -2167
  206. package/__tests__/coverage/src/index.html +0 -266
  207. package/__tests__/coverage/src/infrastructure/repositories/hybrid-memory-repository.ts.html +0 -1633
  208. package/__tests__/coverage/src/infrastructure/repositories/index.html +0 -116
  209. package/__tests__/coverage/src/migration.ts.html +0 -2092
  210. package/__tests__/coverage/src/query-builder.ts.html +0 -1711
  211. package/__tests__/coverage/src/sqlite-backend.ts.html +0 -2281
  212. package/__tests__/coverage/src/sqljs-backend.ts.html +0 -2374
  213. package/__tests__/coverage/src/types.ts.html +0 -2266
  214. package/benchmarks/cache-hit-rate.bench.ts +0 -535
  215. package/benchmarks/hnsw-indexing.bench.ts +0 -552
  216. package/benchmarks/memory-write.bench.ts +0 -469
  217. package/benchmarks/vector-search.bench.ts +0 -449
  218. package/docs/AGENTDB-INTEGRATION.md +0 -388
  219. package/docs/CROSS_PLATFORM.md +0 -505
  220. package/docs/WINDOWS_SUPPORT.md +0 -422
  221. package/examples/agentdb-example.ts +0 -345
  222. package/examples/cross-platform-usage.ts +0 -326
  223. package/framework/benchmark.ts +0 -112
  224. package/src/agentdb-adapter.ts +0 -884
  225. package/src/agentdb-backend.test.ts +0 -339
  226. package/src/agentdb-backend.ts +0 -1016
  227. package/src/application/commands/delete-memory.command.ts +0 -172
  228. package/src/application/commands/store-memory.command.ts +0 -103
  229. package/src/application/index.ts +0 -36
  230. package/src/application/queries/search-memory.query.ts +0 -237
  231. package/src/application/services/memory-application-service.ts +0 -236
  232. package/src/cache-manager.ts +0 -516
  233. package/src/database-provider.test.ts +0 -364
  234. package/src/database-provider.ts +0 -511
  235. package/src/domain/entities/memory-entry.ts +0 -289
  236. package/src/domain/index.ts +0 -35
  237. package/src/domain/repositories/memory-repository.interface.ts +0 -120
  238. package/src/domain/services/memory-domain-service.ts +0 -403
  239. package/src/hnsw-index.ts +0 -1013
  240. package/src/hybrid-backend.test.ts +0 -399
  241. package/src/hybrid-backend.ts +0 -694
  242. package/src/index.ts +0 -515
  243. package/src/infrastructure/index.ts +0 -23
  244. package/src/infrastructure/repositories/hybrid-memory-repository.ts +0 -516
  245. package/src/migration.ts +0 -669
  246. package/src/query-builder.ts +0 -542
  247. package/src/sqlite-backend.ts +0 -732
  248. package/src/sqljs-backend.ts +0 -763
  249. package/src/types.ts +0 -727
  250. package/tmp.json +0 -0
  251. package/tsconfig.json +0 -9
  252. package/tsconfig.tsbuildinfo +0 -1
  253. package/verify-cross-platform.ts +0 -170
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Agent-Scoped Memory - Support for Claude Code's 3-scope agent memory directories
3
+ *
4
+ * Claude Code organizes agent memory into three scopes:
5
+ * - **project**: Shared across all collaborators (checked into git)
6
+ * - **local**: Machine-specific, not shared (gitignored)
7
+ * - **user**: Global per-user, spans all projects
8
+ *
9
+ * Each scope stores agent-specific memory in a named subdirectory,
10
+ * enabling isolated yet transferable knowledge between agents.
11
+ *
12
+ * @module @claude-flow/memory/agent-memory-scope
13
+ */
14
+ import type { IMemoryBackend } from './types.js';
15
+ import { AutoMemoryBridge } from './auto-memory-bridge.js';
16
+ import type { AutoMemoryBridgeConfig, InsightCategory } from './auto-memory-bridge.js';
17
+ /** Claude Code's 3-scope agent memory system */
18
+ export type AgentMemoryScope = 'project' | 'local' | 'user';
19
+ /** Configuration for agent-scoped memory bridge */
20
+ export interface AgentScopedConfig extends AutoMemoryBridgeConfig {
21
+ /** Agent name (used in directory path) */
22
+ agentName: string;
23
+ /** Memory scope */
24
+ scope: AgentMemoryScope;
25
+ }
26
+ /** Options for knowledge transfer between agents */
27
+ export interface TransferOptions {
28
+ /** Source namespace to transfer from */
29
+ sourceNamespace: string;
30
+ /** Minimum confidence to include (default: 0.8) */
31
+ minConfidence?: number;
32
+ /** Maximum entries to transfer (default: 20) */
33
+ maxEntries?: number;
34
+ /** Filter by categories */
35
+ categories?: InsightCategory[];
36
+ }
37
+ /** Result of a knowledge transfer */
38
+ export interface TransferResult {
39
+ /** Number of entries transferred */
40
+ transferred: number;
41
+ /** Number of entries skipped (below threshold or duplicate) */
42
+ skipped: number;
43
+ }
44
+ /**
45
+ * Resolve the agent memory directory for a given agent name, scope, and working directory.
46
+ *
47
+ * Path resolution matches Claude Code binary behavior:
48
+ * ```
49
+ * project: <gitRoot>/.claude/agent-memory/<agentName>/
50
+ * local: <gitRoot>/.claude/agent-memory-local/<agentName>/
51
+ * user: ~/.claude/agent-memory/<agentName>/
52
+ * ```
53
+ *
54
+ * Agent names are sanitized to prevent path traversal attacks.
55
+ *
56
+ * @param agentName - The agent identifier
57
+ * @param scope - Memory scope: project, local, or user
58
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
59
+ * @returns Absolute path to the agent's memory directory
60
+ */
61
+ export declare function resolveAgentMemoryDir(agentName: string, scope: AgentMemoryScope, workingDir?: string): string;
62
+ /**
63
+ * Create an AutoMemoryBridge configured for a specific agent scope.
64
+ *
65
+ * This is the primary factory for creating scoped bridges. It resolves
66
+ * the correct memory directory based on agent name and scope, then
67
+ * delegates to AutoMemoryBridge for the actual sync logic.
68
+ *
69
+ * @param backend - The AgentDB memory backend
70
+ * @param config - Agent-scoped configuration
71
+ * @returns A configured AutoMemoryBridge instance
72
+ *
73
+ * @example
74
+ * ```typescript
75
+ * const bridge = createAgentBridge(backend, {
76
+ * agentName: 'coder',
77
+ * scope: 'project',
78
+ * syncMode: 'on-write',
79
+ * });
80
+ * await bridge.recordInsight({ ... });
81
+ * ```
82
+ */
83
+ export declare function createAgentBridge(backend: IMemoryBackend, config: AgentScopedConfig): AutoMemoryBridge;
84
+ /**
85
+ * Transfer knowledge from a source backend namespace into a target bridge.
86
+ *
87
+ * Queries high-confidence entries from the source and records them as
88
+ * insights in the target bridge. Useful for cross-agent knowledge sharing
89
+ * or promoting learnings from one scope to another.
90
+ *
91
+ * @param sourceBackend - Backend to query entries from
92
+ * @param targetBridge - Bridge to record insights into
93
+ * @param options - Transfer options (namespace, filters, limits)
94
+ * @returns Transfer result with counts of transferred and skipped entries
95
+ *
96
+ * @example
97
+ * ```typescript
98
+ * const result = await transferKnowledge(sourceBackend, targetBridge, {
99
+ * sourceNamespace: 'learnings',
100
+ * minConfidence: 0.9,
101
+ * maxEntries: 10,
102
+ * categories: ['architecture', 'security'],
103
+ * });
104
+ * console.log(`Transferred ${result.transferred}, skipped ${result.skipped}`);
105
+ * ```
106
+ */
107
+ export declare function transferKnowledge(sourceBackend: IMemoryBackend, targetBridge: AutoMemoryBridge, options: TransferOptions): Promise<TransferResult>;
108
+ /**
109
+ * List all agent scopes and their agents for the current project.
110
+ *
111
+ * Scans the three scope directories (project, local, user) and returns
112
+ * the agent names found in each. Useful for discovery and diagnostics.
113
+ *
114
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
115
+ * @returns Array of scope/agents pairs
116
+ *
117
+ * @example
118
+ * ```typescript
119
+ * const scopes = listAgentScopes('/workspaces/my-project');
120
+ * // [
121
+ * // { scope: 'project', agents: ['coder', 'tester'] },
122
+ * // { scope: 'local', agents: ['researcher'] },
123
+ * // { scope: 'user', agents: ['planner'] },
124
+ * // ]
125
+ * ```
126
+ */
127
+ export declare function listAgentScopes(workingDir?: string): Array<{
128
+ scope: AgentMemoryScope;
129
+ agents: string[];
130
+ }>;
131
+ //# sourceMappingURL=agent-memory-scope.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-memory-scope.d.ts","sourceRoot":"","sources":["../src/agent-memory-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EACV,sBAAsB,EAEtB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAIjC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5D,mDAAmD;AACnD,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AA2CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,gBAAgB,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAyBR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,CAWlB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,gBAAgB,EAC9B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAwDzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,UAAU,CAAC,EAAE,MAAM,GAClB,KAAK,CAAC;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAkBtD"}
@@ -0,0 +1,223 @@
1
+ /**
2
+ * Agent-Scoped Memory - Support for Claude Code's 3-scope agent memory directories
3
+ *
4
+ * Claude Code organizes agent memory into three scopes:
5
+ * - **project**: Shared across all collaborators (checked into git)
6
+ * - **local**: Machine-specific, not shared (gitignored)
7
+ * - **user**: Global per-user, spans all projects
8
+ *
9
+ * Each scope stores agent-specific memory in a named subdirectory,
10
+ * enabling isolated yet transferable knowledge between agents.
11
+ *
12
+ * @module @claude-flow/memory/agent-memory-scope
13
+ */
14
+ import * as path from 'node:path';
15
+ import { existsSync, readdirSync, statSync } from 'node:fs';
16
+ import { AutoMemoryBridge } from './auto-memory-bridge.js';
17
+ // ===== Internal Helpers =====
18
+ /**
19
+ * Find the git root directory by walking up from a starting directory.
20
+ * Synchronous variant for path resolution (no async needed for stat checks).
21
+ */
22
+ function findGitRootSync(dir) {
23
+ let current = path.resolve(dir);
24
+ const root = path.parse(current).root;
25
+ while (current !== root) {
26
+ if (existsSync(path.join(current, '.git'))) {
27
+ return current;
28
+ }
29
+ current = path.dirname(current);
30
+ }
31
+ return null;
32
+ }
33
+ /**
34
+ * List agent subdirectories inside a given directory.
35
+ * Returns an empty array if the directory does not exist or is unreadable.
36
+ */
37
+ function listAgentsInDir(dir) {
38
+ if (!existsSync(dir))
39
+ return [];
40
+ try {
41
+ return readdirSync(dir).filter((name) => {
42
+ try {
43
+ return statSync(path.join(dir, name)).isDirectory();
44
+ }
45
+ catch {
46
+ return false;
47
+ }
48
+ });
49
+ }
50
+ catch {
51
+ return [];
52
+ }
53
+ }
54
+ // ===== Public Functions =====
55
+ /**
56
+ * Resolve the agent memory directory for a given agent name, scope, and working directory.
57
+ *
58
+ * Path resolution matches Claude Code binary behavior:
59
+ * ```
60
+ * project: <gitRoot>/.claude/agent-memory/<agentName>/
61
+ * local: <gitRoot>/.claude/agent-memory-local/<agentName>/
62
+ * user: ~/.claude/agent-memory/<agentName>/
63
+ * ```
64
+ *
65
+ * Agent names are sanitized to prevent path traversal attacks.
66
+ *
67
+ * @param agentName - The agent identifier
68
+ * @param scope - Memory scope: project, local, or user
69
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
70
+ * @returns Absolute path to the agent's memory directory
71
+ */
72
+ export function resolveAgentMemoryDir(agentName, scope, workingDir) {
73
+ // Sanitize agent name to prevent path traversal
74
+ const safeName = agentName.replace(/[^a-zA-Z0-9_-]/g, '_');
75
+ if (scope === 'user') {
76
+ const home = process.env.HOME
77
+ || process.env.USERPROFILE
78
+ || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : '');
79
+ if (!home) {
80
+ throw new Error('Cannot determine home directory: HOME, USERPROFILE, and HOMEDRIVE+HOMEPATH are all undefined');
81
+ }
82
+ return path.join(home, '.claude', 'agent-memory', safeName);
83
+ }
84
+ // For project and local scopes, find git root
85
+ const effectiveDir = workingDir || process.cwd();
86
+ const gitRoot = findGitRootSync(effectiveDir);
87
+ const baseDir = gitRoot || effectiveDir;
88
+ if (scope === 'local') {
89
+ return path.join(baseDir, '.claude', 'agent-memory-local', safeName);
90
+ }
91
+ // scope === 'project'
92
+ return path.join(baseDir, '.claude', 'agent-memory', safeName);
93
+ }
94
+ /**
95
+ * Create an AutoMemoryBridge configured for a specific agent scope.
96
+ *
97
+ * This is the primary factory for creating scoped bridges. It resolves
98
+ * the correct memory directory based on agent name and scope, then
99
+ * delegates to AutoMemoryBridge for the actual sync logic.
100
+ *
101
+ * @param backend - The AgentDB memory backend
102
+ * @param config - Agent-scoped configuration
103
+ * @returns A configured AutoMemoryBridge instance
104
+ *
105
+ * @example
106
+ * ```typescript
107
+ * const bridge = createAgentBridge(backend, {
108
+ * agentName: 'coder',
109
+ * scope: 'project',
110
+ * syncMode: 'on-write',
111
+ * });
112
+ * await bridge.recordInsight({ ... });
113
+ * ```
114
+ */
115
+ export function createAgentBridge(backend, config) {
116
+ const memoryDir = resolveAgentMemoryDir(config.agentName, config.scope, config.workingDir);
117
+ return new AutoMemoryBridge(backend, {
118
+ ...config,
119
+ memoryDir,
120
+ });
121
+ }
122
+ /**
123
+ * Transfer knowledge from a source backend namespace into a target bridge.
124
+ *
125
+ * Queries high-confidence entries from the source and records them as
126
+ * insights in the target bridge. Useful for cross-agent knowledge sharing
127
+ * or promoting learnings from one scope to another.
128
+ *
129
+ * @param sourceBackend - Backend to query entries from
130
+ * @param targetBridge - Bridge to record insights into
131
+ * @param options - Transfer options (namespace, filters, limits)
132
+ * @returns Transfer result with counts of transferred and skipped entries
133
+ *
134
+ * @example
135
+ * ```typescript
136
+ * const result = await transferKnowledge(sourceBackend, targetBridge, {
137
+ * sourceNamespace: 'learnings',
138
+ * minConfidence: 0.9,
139
+ * maxEntries: 10,
140
+ * categories: ['architecture', 'security'],
141
+ * });
142
+ * console.log(`Transferred ${result.transferred}, skipped ${result.skipped}`);
143
+ * ```
144
+ */
145
+ export async function transferKnowledge(sourceBackend, targetBridge, options) {
146
+ const { sourceNamespace, minConfidence = 0.8, maxEntries = 20, categories, } = options;
147
+ let transferred = 0;
148
+ let skipped = 0;
149
+ // Query high-confidence entries from source (fetch extra to allow for filtering)
150
+ const entries = await sourceBackend.query({
151
+ type: 'hybrid',
152
+ namespace: sourceNamespace,
153
+ tags: ['insight'],
154
+ limit: maxEntries * 2,
155
+ });
156
+ for (const entry of entries) {
157
+ if (transferred >= maxEntries)
158
+ break;
159
+ const confidence = entry.metadata?.confidence || 0;
160
+ if (confidence < minConfidence) {
161
+ skipped++;
162
+ continue;
163
+ }
164
+ // Filter by category if specified
165
+ const entryCategory = entry.metadata?.category;
166
+ if (categories &&
167
+ categories.length > 0 &&
168
+ entryCategory &&
169
+ !categories.includes(entryCategory)) {
170
+ skipped++;
171
+ continue;
172
+ }
173
+ // Record as insight in target bridge
174
+ const insight = {
175
+ category: entryCategory || 'project-patterns',
176
+ summary: entry.metadata?.summary || entry.content.split('\n')[0],
177
+ detail: entry.content,
178
+ source: `transfer:${sourceNamespace}`,
179
+ confidence,
180
+ agentDbId: entry.id,
181
+ };
182
+ await targetBridge.recordInsight(insight);
183
+ transferred++;
184
+ }
185
+ return { transferred, skipped };
186
+ }
187
+ /**
188
+ * List all agent scopes and their agents for the current project.
189
+ *
190
+ * Scans the three scope directories (project, local, user) and returns
191
+ * the agent names found in each. Useful for discovery and diagnostics.
192
+ *
193
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
194
+ * @returns Array of scope/agents pairs
195
+ *
196
+ * @example
197
+ * ```typescript
198
+ * const scopes = listAgentScopes('/workspaces/my-project');
199
+ * // [
200
+ * // { scope: 'project', agents: ['coder', 'tester'] },
201
+ * // { scope: 'local', agents: ['researcher'] },
202
+ * // { scope: 'user', agents: ['planner'] },
203
+ * // ]
204
+ * ```
205
+ */
206
+ export function listAgentScopes(workingDir) {
207
+ const effectiveDir = workingDir || process.cwd();
208
+ const gitRoot = findGitRootSync(effectiveDir);
209
+ const baseDir = gitRoot || effectiveDir;
210
+ const home = process.env.HOME
211
+ || process.env.USERPROFILE
212
+ || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : '')
213
+ || '';
214
+ const projectDir = path.join(baseDir, '.claude', 'agent-memory');
215
+ const localDir = path.join(baseDir, '.claude', 'agent-memory-local');
216
+ const userDir = path.join(home, '.claude', 'agent-memory');
217
+ return [
218
+ { scope: 'project', agents: listAgentsInDir(projectDir) },
219
+ { scope: 'local', agents: listAgentsInDir(localDir) },
220
+ { scope: 'user', agents: listAgentsInDir(userDir) },
221
+ ];
222
+ }
223
+ //# sourceMappingURL=agent-memory-scope.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-memory-scope.js","sourceRoot":"","sources":["../src/agent-memory-scope.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Tests for Agent-Scoped Memory
3
+ *
4
+ * TDD London School (mock-first) tests for the 3-scope agent memory system.
5
+ * Uses vi.mock for ESM-compatible fs mocking.
6
+ */
7
+ export {};
8
+ //# sourceMappingURL=agent-memory-scope.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-memory-scope.test.d.ts","sourceRoot":"","sources":["../src/agent-memory-scope.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}