@swarmvaultai/engine 1.4.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 `@swarmvaultai/engine` is the runtime library behind SwarmVault.
 
-It exposes the primitives for initializing a workspace, ingesting sources, importing an inbox, compiling a wiki, querying the vault, running lint, serving the graph viewer, watching the inbox, and exposing the vault over MCP.
+It exposes the primitives for initializing a workspace, ingesting sources, importing an inbox, compiling a wiki, querying the vault, recording agent tasks, maintaining retrieval, running lint, serving the graph viewer, watching the inbox, and exposing the vault over MCP.
 
 ## Who This Is For
 
@@ -22,16 +22,21 @@ import {
   addInput,
   addManagedSource,
   benchmarkVault,
+  buildContextPack,
   compileVault,
   createMcpServer,
   createWebSearchAdapter,
+  deleteContextPack,
   deleteManagedSource,
   defaultVaultConfig,
   defaultVaultSchema,
+  doctorRetrieval,
   exploreVault,
   exportGraphFormat,
   exportGraphHtml,
   explainGraphVault,
+  finishMemoryTask,
+  getRetrievalStatus,
   getWatchStatus,
   getGitHookStatus,
   importInbox,
@@ -42,6 +47,8 @@ import {
   getWebSearchAdapterForTask,
   lintVault,
   listGodNodes,
+  listContextPacks,
+  listMemoryTasks,
   listManagedSourceRecords,
   listSchedules,
   loadVaultConfig,
@@ -51,20 +58,26 @@ import {
   pushGraphNeo4j,
   queryGraphVault,
   queryVault,
+  readContextPack,
+  readMemoryTask,
+  rebuildRetrievalIndex,
   reloadManagedSources,
+  resumeMemoryTask,
   runWatchCycle,
   runSchedule,
   searchVault,
   serveSchedules,
   startGraphServer,
+  startMemoryTask,
   startMcpServer,
   syncTrackedRepos,
   uninstallGitHooks,
+  updateMemoryTask,
   watchVault,
 } from "@swarmvaultai/engine";
 ```
 
-The engine also exports the main runtime types for providers, graph artifacts, pages, manifests, query results, lint findings, and watch records.
+The engine also exports the main runtime types for providers, graph artifacts, pages, manifests, query results, task records, retrieval status, lint findings, and watch records.
 
 ## Example
 
@@ -73,21 +86,31 @@ import {
   addInput,
   addManagedSource,
   benchmarkVault,
+  buildContextPack,
   compileVault,
+  doctorRetrieval,
   exploreVault,
   exportGraphHtml,
   exportGraphFormat,
+  finishMemoryTask,
+  getRetrievalStatus,
   getWatchStatus,
   importInbox,
   initVault,
   installGitHooks,
+  listMemoryTasks,
   listManagedSourceRecords,
   loadVaultSchemas,
   pushGraphNeo4j,
   queryGraphVault,
   queryVault,
+  readContextPack,
+  rebuildRetrievalIndex,
+  resumeMemoryTask,
   reloadManagedSources,
   runWatchCycle,
+  startMemoryTask,
+  updateMemoryTask,
   watchVault
 } from "@swarmvaultai/engine";
 
@@ -106,6 +129,31 @@ console.log(benchmark.avgQueryTokens);
 
 const saved = await queryVault(rootDir, { question: "What changed most recently?" });
 console.log(saved.savedPath);
+console.log(await getRetrievalStatus(rootDir));
+
+const contextPack = await buildContextPack(rootDir, {
+  goal: "Implement the auth refactor",
+  target: "./src",
+  budgetTokens: 8000
+});
+console.log(contextPack.markdownPath);
+
+const memory = await startMemoryTask(rootDir, {
+  goal: "Implement the auth refactor",
+  target: "./src",
+  agent: "codex"
+});
+await updateMemoryTask(rootDir, memory.task.id, {
+  decision: "Keep the implementation local-first and file-backed.",
+  changedPath: "packages/engine/src/memory.ts"
+});
+await finishMemoryTask(rootDir, memory.task.id, {
+  outcome: "Task ledger shipped behind CLI, MCP, graph, and viewer surfaces."
+});
+console.log((await readMemoryTask(rootDir, memory.task.id)).status);
+console.log((await listMemoryTasks(rootDir)).length);
+console.log((await resumeMemoryTask(rootDir, memory.task.id)).content);
+console.log(await doctorRetrieval(rootDir));
 
 const graphQuery = await queryGraphVault(rootDir, "Which nodes bridge the biggest communities?");
 console.log(graphQuery.summary);
@@ -211,6 +259,7 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `benchmarkVault(rootDir, { questions })` writes `state/benchmark.json` and folds the latest benchmark summary into `wiki/graph/report.md` and `wiki/graph/report.json`
 - semantic graph query and embedding-backed similarity enrichment cache vectors under `state/embeddings.json` so graph-semantic refresh stays incremental
 - `queryVault(rootDir, { question, save, format, review })` answers against the compiled vault using the same schema layer and saves by default
+- `buildContextPack(rootDir, { goal, target, budgetTokens, format })` builds an agent-ready evidence bundle with relevant pages, graph nodes, edges, hyperedges, citations, token-budget accounting, and explicit omitted entries
 - `exploreVault(rootDir, { question, steps, format, review })` runs a save-first multi-step exploration loop and writes a hub page plus step outputs
 - `searchVault(rootDir, query, limit)` searches compiled pages directly
 - `queryGraphVault(rootDir, question, { traversal, budget })` runs deterministic local graph search, preferring semantic seed matches from `tasks.embeddingProvider` when configured and falling back to lexical search plus matching group patterns otherwise
@@ -219,6 +268,7 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `listGraphHyperedges(rootDir, target?, limit?)` returns graph hyperedges globally or for a specific node/page target
 - `listGodNodes(rootDir, limit)` returns the most connected bridge-heavy graph nodes
 - `buildGraphShareArtifact(...)`, `renderGraphShareMarkdown(...)`, `renderGraphShareSvg(...)`, `renderGraphSharePreviewHtml(...)`, and `renderGraphShareBundleFiles(...)` produce the post-ready text, 1200x630 visual card, self-contained HTML preview, and portable share kit used by `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, `wiki/graph/share-kit/`, and the CLI `graph share` command
+- `listContextPacks(rootDir)`, `readContextPack(rootDir, id)`, and `deleteContextPack(rootDir, id)` manage saved context-pack artifacts under `state/context-packs/`
 - project-aware compile also builds `wiki/projects/index.md` plus `wiki/projects/<project>/index.md` rollups without duplicating page trees
 - human-authored insight pages in `wiki/insights/` are indexed into search and available to query without being rewritten by compile
 - `chart` and `image` formats save wrapper markdown pages plus local output assets under `wiki/outputs/assets/<slug>/`
@@ -252,7 +302,7 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `exportGraphFormat(rootDir, "svg" | "graphml" | "cypher", outputPath)` exports the graph into interoperable file formats
 - `pushGraphNeo4j(rootDir, options)` upserts the current graph into Neo4j over Bolt/Aura with shared-database-safe `vaultId` namespacing
 
-The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, ingestion, compile, lint, graph report reads, hyperedge reads, and graph-native read operations such as graph query, node explain, neighbor lookup, shortest path, and god-node listing, along with resources for config, graph, manifests, schema, page content, and session artifacts.
+The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, context-pack build/read/list, task start/update/finish/list/read/resume, compatibility memory task tools, retrieval status/rebuild/doctor, ingestion, compile, lint, graph report reads, hyperedge reads, and graph-native read operations such as graph query, node explain, neighbor lookup, shortest path, and god-node listing, along with resources for config, graph, manifests, schema, page content, context-pack listings, task listings, compatibility memory task listings, and session artifacts.
 
 ## Artifacts
 
@@ -264,6 +314,8 @@ Running the engine produces a local workspace with these main areas:
 - `raw/assets/`: copied attachments referenced by ingested markdown bundles and remote URL ingests
 - `wiki/`: generated markdown pages, the append-only `log.md` activity trail, staged candidates, saved query outputs, exploration hub pages, and a human-only `insights/` area
 - `wiki/graph/`: generated graph report pages, markdown/SVG share cards, the portable `share-kit/`, and per-community summaries derived from `state/graph.json`
+- `wiki/context/`: markdown companions for saved context packs
+- `wiki/memory/`: markdown index and task pages for the agent task ledger
 - `wiki/graph/report.json`: machine-readable graph report data used by the viewer and export surfaces
 - `wiki/outputs/assets/`: local chart/image artifacts and JSON manifests for saved visual outputs
 - `wiki/code/`: generated module pages for ingested code sources
@@ -277,7 +329,9 @@ Running the engine produces a local workspace with these main areas:
 - `state/code-index.json`: repo-aware code module aliases and local resolution data
 - `state/benchmark.json`: latest benchmark/trust summary for the current vault
 - `state/graph.json`: compiled graph, including semantic-similarity edges and hyperedge-style group patterns
-- `state/search.sqlite`: full-text index
+- `state/context-packs/`: JSON context-pack artifacts for agent kickoff, review, and handoff workflows
+- `state/memory/tasks/`: JSON task records for the agent task ledger
+- `state/retrieval/`: local retrieval index directory, including the SQLite FTS shard and manifest
 - `state/sessions/`: canonical session artifacts
 - `state/approvals/`: staged review bundles from `compileVault({ approve: true })`
 - `state/schedules/`: persisted schedule state and leases