akm-cli 0.10.261124 → 0.10.261125-beta.1

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 (40) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/dist/cli.js +10 -0
  3. package/dist/commands/feedback-cli.js +12 -3
  4. package/dist/commands/health/semantic-search-check.js +12 -2
  5. package/dist/commands/health.js +8 -15
  6. package/dist/commands/lint/index.js +6 -6
  7. package/dist/commands/read/knowledge.js +8 -8
  8. package/dist/commands/read/related.js +3 -9
  9. package/dist/commands/read/show.js +17 -9
  10. package/dist/commands/sources/bundle-cli.js +1 -0
  11. package/dist/commands/sources/installed-stashes.js +36 -27
  12. package/dist/core/asset/resolve-ref.js +8 -0
  13. package/dist/core/common.js +21 -0
  14. package/dist/core/endpoint-url.js +4 -4
  15. package/dist/core/events.js +8 -2
  16. package/dist/core/file-lock.js +52 -1
  17. package/dist/core/state-db.js +47 -15
  18. package/dist/core/stdio-reader-gone.js +19 -0
  19. package/dist/core/write-source.js +2 -2
  20. package/dist/indexer/index-build.js +6 -3
  21. package/dist/indexer/index-readiness.js +30 -4
  22. package/dist/indexer/indexer.js +56 -8
  23. package/dist/indexer/search/db-search.js +7 -1
  24. package/dist/indexer/search/search-source.js +23 -25
  25. package/dist/indexer/usage/usage-events.js +13 -4
  26. package/dist/registry/origin-resolve.js +2 -3
  27. package/dist/scripts/akm-migrate-node.js +118 -72
  28. package/dist/scripts/akm-migrate.js +118 -72
  29. package/dist/setup/endpoint.js +1 -1
  30. package/dist/storage/repositories/index-connection.js +44 -41
  31. package/dist/storage/repositories/index-entries-repository.js +14 -7
  32. package/dist/storage/repositories/index-entry-schema.js +7 -5
  33. package/dist/storage/repositories/index-schema.js +23 -0
  34. package/dist/workspace/assets.js +24 -44
  35. package/dist/workspace/bundle-files.js +2 -2
  36. package/dist/workspace/documents.js +7 -12
  37. package/dist/workspace/graph-topics.js +249 -0
  38. package/dist/workspace/graph.js +68 -4
  39. package/docs/reference/workspace.md +21 -4
  40. package/package.json +1 -1
@@ -200,9 +200,13 @@ them, in column form, so 30,000 assets stay a few megabytes:
200
200
  "unresolvedLinks": 2,
201
201
  "kinds": ["xref", "links_to"],
202
202
  "nodes": { "ref": ["team-wiki//knowledge/a"], "title": ["A"], "type": [0], "bundle": [0], "belief": [-1],
203
- "shows": [12], "searches": [40] },
203
+ "shows": [12], "searches": [40], "lastShownAt": ["2026-11-02T09:14:03Z"],
204
+ "modifiedAt": ["2026-03-30T17:02:11.000Z"], "positive": [2], "negative": [0], "topic": [4] },
204
205
  "links": { "from": [0], "to": [3], "kind": [1] },
205
- "meaning": { "embedded": 29840, "xyz": [12.5, -40.1, 3.2] }
206
+ "meaning": { "embedded": 29840, "xyz": [12.5, -40.1, 3.2] },
207
+ "topics": [{ "label": "deploy · canary", "terms": ["deploy", "canary", "rollout"], "size": 812,
208
+ "related": [{ "topic": 7, "cosine": 0.81 }] }],
209
+ "duplicates": { "threshold": 0.96, "a": [0], "b": [9], "cosine": [0.9871], "truncated": false }
206
210
  }
207
211
  ```
208
212
 
@@ -213,13 +217,26 @@ the asset that declares it to its target; `unresolvedLinks` counts the declared
213
217
  target is missing, of a type that is not returned, or in a bundle that is not enabled. `shows` and `searches` are
214
218
  counted from the usage events when the operation is called: events of source `user` (people and their agent
215
219
  sessions, not scheduled tasks or Improve) at or after `use.since`, the start of the usage retention window. They are
216
- zero, and the note says so, when no usage history is available. `meaning` places each asset with a stored embedding
220
+ zero, and the note says so, when no usage history is available. `lastShownAt` is the latest of those shows (UTC), `null`
221
+ when there is none in the window. `positive` and `negative` count feedback from people inside the retention window, as
222
+ search ranks by it (a negative answered by an accepted fix does not count). `modifiedAt` is the file's modification
223
+ time, `null` when it cannot be read; in a Git checkout it is when the file was last written there, not its last commit. `meaning` places each asset with a stored embedding
217
224
  of the index's current model in three dimensions (three coordinates per node, `null` for one with no embedding): its
218
225
  projection on the three principal components of the vectors, so assets with similar content land near each other. The
219
226
  components are found from an evenly spaced sample of at most 4,000 vectors and kept for the life of the process until
220
227
  the index's embedding model or full build changes; an asset embedded since is projected onto them. The work yields to
221
228
  the event loop as it goes, so a host's other requests are served meanwhile. `meaning` is `null` when the index has no
222
- embeddings. `available` is `false`, with a `note`,
229
+ embeddings.
230
+
231
+ `topics` groups the embedded assets by meaning: spherical k-means on their stored vectors, about √(n/2) topics (2 to 36),
232
+ largest first, the centres found from an evenly spaced sample of at most 4,000 vectors from a fixed start, so the same
233
+ index gives the same topics. A topic's `terms` are the words of its assets' paths and titles most particular to it
234
+ (frequent in the topic, rare in the library), and its `label` the first two; `related` names the three topics whose
235
+ centres are nearest, with the cosine between them. `nodes.topic` indexes `topics`, `-1` for an asset with no embedding.
236
+ `duplicates` lists pairs of assets of one topic whose vectors have a cosine of at least `threshold` (0.96), most alike
237
+ first, at most 2,000 (`truncated` says there were more); pairs across topics are not compared. Both are `[]` and `null`
238
+ without at least eight embedded assets. They are found once per index build and kept, like the projection: the first
239
+ read of a 20,000-asset index takes several seconds. `available` is `false`, with a `note`,
223
240
  when there is no index.
224
241
 
225
242
  ## `bundles.list`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261124",
3
+ "version": "0.10.261125-beta.1",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [