skillscript-runtime 0.13.7 → 0.14.0

package/examples/connectors/{MemoryStoreTemplate → DataStoreTemplate}/README.md

@@ -1,10 +1,10 @@
-# MemoryStoreTemplate — fork-me skeleton
+# DataStoreTemplate — fork-me skeleton
 
-A skeleton `MemoryStore` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
+A skeleton `DataStore` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
 
 Use this when you want skillscript memories backed by:
 - A vector database (Pinecone, Weaviate, Qdrant, Chroma)
-- A memory system (AMP, hosted memory API)
+- A data store backing (memory broker like AMP, hosted memory API, vector DB, etc.)
 - A different SQL flavor (Postgres + pgvector, MySQL)
 - An HTTP CRUD service
 - Anything else with query + write semantics
@@ -12,32 +12,32 @@ Use this when you want skillscript memories backed by:
 ## The three legs
 
 ```
-MemoryStore (choose which connector)
-   ├── SqliteMemoryStore (bundled, SQLite + FTS5 — src/connectors/memory-store.ts)
+DataStore (choose which connector)
+   ├── SqliteDataStore (bundled, SQLite + FTS5 — src/connectors/data-store.ts)
    ├── (no other bundled impl — vector DBs and remote services are adopter-side)
    └── Your fork from this template
 ```
 
-The runtime is substrate-agnostic. Memories don't know which backend they're stored against — the contract is the `MemoryStore` interface, and any class implementing it works.
+The runtime is substrate-agnostic. Memories don't know which backend they're stored against — the contract is the `DataStore` interface, and any class implementing it works.
 
 ## Forking workflow
 
 ```bash
-cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore
+cp -r examples/connectors/DataStoreTemplate examples/connectors/MyDataStore
 ```
 
-1. **Rename the class.** Convention: `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `PostgresMemoryStore`, `AmpMemoryStore`).
-2. **Define your config interface.** Edit `MemoryStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, index name, etc.).
+1. **Rename the class.** Convention: `<Substrate>DataStore` (e.g., `PineconeDataStore`, `PostgresDataStore`, `AmpDataStore`).
+2. **Define your config interface.** Edit `DataStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, index name, etc.).
 3. **Implement each method.** Three methods + `staticCapabilities()`. Each has a TODO comment in the skeleton explaining what to do.
 4. **Update `staticCapabilities()`** to declare what your impl actually supports. The runtime + lint consult these flags before exercising features.
 5. **Wire from your adopter bootstrap:**
 
    ```typescript
    import { Registry } from "skillscript-runtime";
-   import { MyMemoryStore } from "./MyMemoryStore.js";
+   import { MyDataStore } from "./MyDataStore.js";
 
    const registry = new Registry();
-   registry.registerMemoryStore("primary", new MyMemoryStore({
+   registry.registerDataStore("primary", new MyDataStore({
      // your config
    }));
    ```
@@ -46,37 +46,37 @@ cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore
 
    ```typescript
    import { describe, it } from "vitest";
-   import { MemoryStoreConformance } from "skillscript-runtime/testing";
-   import { MyMemoryStore } from "./MyMemoryStore.js";
+   import { DataStoreConformance } from "skillscript-runtime/testing";
+   import { MyDataStore } from "./MyDataStore.js";
 
-   describe("MyMemoryStore conformance", () => {
-     const tests = MemoryStoreConformance.buildTests({
-       build: () => new MyMemoryStore({ /* test config */ }),
-       ctor: MyMemoryStore,
+   describe("MyDataStore conformance", () => {
+     const tests = DataStoreConformance.buildTests({
+       build: () => new MyDataStore({ /* test config */ }),
+       ctor: MyDataStore,
      });
      for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
    });
    ```
 
-   The conformance suite verifies your impl honors the contract: method presence, return-type shape, capability flag self-consistency. Passes → runtime treats your impl interchangeably with `SqliteMemoryStore`.
+   The conformance suite verifies your impl honors the contract: method presence, return-type shape, capability flag self-consistency. Passes → runtime treats your impl interchangeably with `SqliteDataStore`.
 
 ## Reference implementation
 
 When in doubt about semantics, read the bundled impl:
 
-- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore`, SQLite + FTS5-backed. Schema lives in `bootstrap()` (memories table + FTS virtual table + AFTER INSERT/UPDATE/DELETE triggers). Single-process. Capability flags: `supports_writes: true`, `supports_tag_filter: true`, FTS only (semantic / rerank false).
+- **`src/connectors/data-store.ts`** — `SqliteDataStore`, SQLite + FTS5-backed. Schema lives in `bootstrap()` (memories table + FTS virtual table + AFTER INSERT/UPDATE/DELETE triggers). Single-process. Capability flags: `supports_writes: true`, `supports_tag_filter: true`, FTS only (semantic / rerank false).
 
 ## Contract surface (3 methods)
 
-The MemoryStore contract is narrower than SkillStore. Three methods + `staticCapabilities()`:
+The DataStore contract is narrower than SkillStore. Three methods + `staticCapabilities()`:
 
 | Method | What it does | When called |
 |---|---|---|
-| `query(filters)` | Read memories by mode + filter; return `PortableMemory[]` | Every `$ memory mode=... query=...` op |
-| `write(entry)` | Persist a new memory; return `{id, created_at}` | Every `$ memory_write content=... -> R` op + `memory_write` skill notify routes |
+| `query(filters)` | Read memories by mode + filter; return `PortableData[]` | Every `$ data_read mode=... query=...` op |
+| `write(entry)` | Persist a new memory; return `{id, created_at}` | Every `$ data_write content=... -> R` op + `data_write` skill notify routes |
 | `manifest()` | Capability snapshot for `runtime_capabilities` discovery | At startup + on-demand from MCP clients |
 
-Per the curated-subset framing in `src/connectors/types.ts`, `PortableMemory` has a 4-tier field model:
+Per the curated-subset framing in `src/connectors/types.ts`, `PortableData` has a 4-tier field model:
 
 1. **Core fields** — `id`, `summary`, `detail`, `score` (always-meaningful)
 2. **Curated substrate subset** — top-level fields with portable concepts: `domain_tags`, `payload_type`, `knowledge_type`, `pinned`, `confidence`, `thread_status`, `recipients`, `expires_at`, `agent_id`, `vault`
@@ -89,8 +89,8 @@ Per the curated-subset framing in `src/connectors/types.ts`, `PortableMemory` ha
 
 `QueryFilters.mode` is the dispatch axis:
 
-- **`"fts"`** — full-text search; substrate-defined (BM25, BM25F, etc.). `SqliteMemoryStore` supports this via FTS5.
-- **`"semantic"`** — embedding-based similarity. Vector-DB substrates support this; `SqliteMemoryStore` does not.
+- **`"fts"`** — full-text search; substrate-defined (BM25, BM25F, etc.). `SqliteDataStore` supports this via FTS5.
+- **`"semantic"`** — embedding-based similarity. Vector-DB substrates support this; `SqliteDataStore` does not.
 - **`"rerank"`** — substrate-defined hybrid (e.g., FTS retrieve + embedding rerank). Optional.
 - **substrate-specific strings** — your fork can define its own modes; document them in `manifest().manifest.supported_modes`.
 
@@ -111,7 +111,7 @@ Honor what your substrate supports; ignore the rest. Document the supported set
 
 ## `write()` semantics
 
-The `MemoryWrite` shape:
+The `DataWrite` shape:
 
 - **`content`** (required) — the memory body
 - **`tags`** (optional) — routed to your substrate's tag mechanism
@@ -125,18 +125,18 @@ If your substrate doesn't support writes (read-only memory like a search index o
 
 ## Wiring against the dashboard / MCP
 
-Runtime hosts honor whichever MemoryStore impl your registry has. To make your fork visible through `skillfile dashboard`:
+Runtime hosts honor whichever DataStore impl your registry has. To make your fork visible through `skillfile dashboard`:
 
-- Write a custom bootstrap that constructs the runtime with your MemoryStore (see `src/bootstrap.ts` for the reference shape)
+- Write a custom bootstrap that constructs the runtime with your DataStore (see `src/bootstrap.ts` for the reference shape)
 - OR (planned future) declare in `~/.skillscript/connectors.json`:
 
   ```json
   {
     "substrate": {
-      "memory_store": {
+      "data_store": {
         "type": "custom",
-        "module": "./my-memory-store.js",
-        "export": "MyMemoryStore",
+        "module": "./my-data-store.js",
+        "export": "MyDataStore",
         "config": { "pineconeApiKey": "${PINECONE_KEY}" }
       }
     }
@@ -145,11 +145,11 @@ Runtime hosts honor whichever MemoryStore impl your registry has. To make your f
 
   Current limitation: sync `bootstrap()` can't dynamic-import, so the `custom` form surfaces an error today. Programmatic bootstrap is the path until async-bootstrap support lands.
 
-## MemoryStore vs SkillStore differences
+## DataStore vs SkillStore differences
 
 Both are substrate-agnostic, but they differ in shape:
 
-| Aspect | SkillStore | MemoryStore |
+| Aspect | SkillStore | DataStore |
 |---|---|---|
 | Methods | 8 (load, query, metadata, versions, store, delete, update_status, manifest) | 3 (query, write, manifest) |
 | Versioning | First-class (`versions()`, `load(name, version)`) | Substrate-side (e.g., `supersededById` in AMP); not in contract |
@@ -158,12 +158,12 @@ Both are substrate-agnostic, but they differ in shape:
 | Curated-subset fields | None | Many (`domain_tags`, `pinned`, `confidence`, `recipients`, etc.) |
 | Forking complexity | Higher (multi-method state machine) | Lower (three methods, simpler semantics) |
 
-The narrower contract is why MemoryStoreTemplate ships sooner + smaller than SkillStoreTemplate.
+The narrower contract is why DataStoreTemplate ships sooner + smaller than SkillStoreTemplate.
 
 ## Further reading
 
 - **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
 - **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — programmatic-bootstrap patterns; two-instance posture
-- **`src/connectors/types.ts`** — authoritative `MemoryStore` interface, `PortableMemory`, `QueryFilters`, `MemoryWrite` types
+- **`src/connectors/types.ts`** — authoritative `DataStore` interface, `PortableData`, `QueryFilters`, `DataWrite` types
 - **`src/testing/conformance.ts`** — the per-contract conformance test suites
-- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore` reference impl + schema
+- **`src/connectors/data-store.ts`** — `SqliteDataStore` reference impl + schema

package/examples/connectors/LocalModelTemplate/README.md

@@ -113,7 +113,7 @@ Adopters wire their custom LocalModel **programmatically** from their bootstrap:
 registry.registerLocalModel("default", new MyLocalModel({ /* config */ }));
 ```
 
-Declarative custom-LocalModel via `connectors.json` `substrate.local_model: {type: "custom", module, export, config}` form is **deferred** until async-bootstrap support lands. Same limitation applies to `SkillStore` and `MemoryStore` custom forms — sync `bootstrap()` can't `await import()`. Not LocalModel-specific.
+Declarative custom-LocalModel via `connectors.json` `substrate.local_model: {type: "custom", module, export, config}` form is **deferred** until async-bootstrap support lands. Same limitation applies to `SkillStore` and `DataStore` custom forms — sync `bootstrap()` can't `await import()`. Not LocalModel-specific.
 
 ## Wiring against the dashboard / MCP
 

package/examples/connectors/McpConnectorTemplate/McpConnectorTemplate.ts

@@ -15,8 +15,8 @@
  *   - `LocalModelMcpConnector` — bridges a registered LocalModel as
  *     `$ llm prompt=...` MCP dispatch. Auto-wired when LocalModel substrate
  *     is configured.
- *   - `MemoryStoreMcpConnector` — bridges a registered MemoryStore as
- *     `$ memory mode=...` MCP dispatch. Auto-wired when MemoryStore substrate
+ *   - `DataStoreMcpConnector` — bridges a registered DataStore as
+ *     `$ data_read mode=...` MCP dispatch. Auto-wired when DataStore substrate
  *     is configured.
  *
  * Fork from this template when none of those fit — e.g.:

package/examples/connectors/McpConnectorTemplate/README.md

@@ -9,7 +9,7 @@ A skeleton `McpConnector` implementation for adopters writing their own. Not run
 | `RemoteMcpConnector` | Stdio bridging to remote MCP servers (`npx mcp-remote ...`). YouTrack, GitHub, Linear, most adopter MCP wiring goes through this. JSON-configurable via `connectors.json`. |
 | `CallbackMcpConnector` | Wraps a JS function. Test rigs + embedder-wired transports where the dispatch is local code. |
 | `LocalModelMcpConnector` | Bridges a registered `LocalModel` as `$ llm prompt=...`. Auto-wired when `substrate.local_model` is set. |
-| `MemoryStoreMcpConnector` | Bridges a registered `MemoryStore` as `$ memory mode=...`. Auto-wired when `substrate.memory_store` is set. |
+| `DataStoreMcpConnector` | Bridges a registered `DataStore` as `$ data_read mode=...`. Auto-wired when `substrate.data_store` is set. |
 
 **Fork this template only when none of those fit** — e.g.:
 
@@ -72,7 +72,7 @@ The bundled impls are the canonical reference:
 - **`src/connectors/mcp-remote.ts`** — `RemoteMcpConnector`. Most comprehensive: stdio framing (LSP and newline), child process lifecycle (spawn → initialize → tools/list cache → SIGTERM/SIGKILL on dispose), `fromConfig` factory with strict validation, per-message timeout discipline. The closest reference for any transport that needs robust lifecycle management.
 - **`src/connectors/mcp.ts`** — `CallbackMcpConnector`. Minimal reference: 60 LOC. The closest reference for embedder-wired transports.
 
-When in doubt, read both + the bridge classes (`local-model-mcp.ts`, `memory-store-mcp.ts`) for how single-substrate bridges work.
+When in doubt, read both + the bridge classes (`local-model-mcp.ts`, `data-store-mcp.ts`) for how single-substrate bridges work.
 
 ## Contract surface (2 methods)
 
@@ -131,15 +131,15 @@ Two registration paths:
 
 The declarative path is the canonical adopter pattern for stdio-bridged remote MCPs. Your fork is for transports the declarative path can't express.
 
-## McpConnector vs. SkillStore / MemoryStore differences
+## McpConnector vs. SkillStore / DataStore differences
 
-| Aspect | McpConnector | SkillStore / MemoryStore |
+| Aspect | McpConnector | SkillStore / DataStore |
 |---|---|---|
 | Methods | 2 (call, manifest) | 3-8 (more state machine) |
 | Cardinality | Many instances per deployment | One singleton per slot |
 | Substrate config | Per-instance via top-level keys | `substrate` section short/object/custom |
 | Class extensibility | `registerConnectorClass()` for adopter-custom classes | Programmatic bootstrap (or `substrate.skill_store: {type: "custom", ...}` once async-bootstrap lands) |
-| Auto-wired bridges | `llm` + `memory` + `memory_write` (LocalModel + MemoryStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
+| Auto-wired bridges | `llm` + `memory` + `data_write` (LocalModel + DataStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
 
 McpConnector is fundamentally the "dispatch to external tools" surface — narrowest contract, broadest range of impls.
 

package/examples/connectors/README.md

@@ -7,9 +7,9 @@ Worked examples + fork-me templates for adopter-written connectors. The bundled
 | Contract | Bundled defaults | Worked example | Fork template |
 |---|---|---|---|
 | `SkillStore` | `FilesystemSkillStore`, `SqliteSkillStore` (in `src/connectors/`) | — | **[SkillStoreTemplate/](./SkillStoreTemplate/)** |
-| `MemoryStore` | `SqliteMemoryStore` (in `src/connectors/`) | — | **[MemoryStoreTemplate/](./MemoryStoreTemplate/)** |
+| `DataStore` | `SqliteDataStore` (in `src/connectors/`) | — | **[DataStoreTemplate/](./DataStoreTemplate/)** |
 | `LocalModel` | `OllamaLocalModel` (in `src/connectors/`; opt-in via substrate config) | — | **[LocalModelTemplate/](./LocalModelTemplate/)** |
-| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `MemoryStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
+| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `DataStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
 | `AgentConnector` | `NoOpAgentConnector` (in `src/connectors/`) | **[HttpWebhookAgentConnector/](./HttpWebhookAgentConnector/)** | — |
 
 **Bundled defaults** are runnable out of the box — wired through `connectors.json` substrate config or programmatic bootstrap.
@@ -35,7 +35,7 @@ Worked examples + fork-me templates for adopter-written connectors. The bundled
 - **[`docs/configuration.md`](../../docs/configuration.md)** — substrate selection via `connectors.json`; programmatic-bootstrap vs declarative patterns
 - **[`docs/adopter-playbook.md`](../../docs/adopter-playbook.md)** — Case 1 vs Case 2 wiring decisions; two-instance posture; upstream-merge-friendly conventions
 - **[`docs/connector-contract-reference.md`](../../docs/connector-contract-reference.md)** — interface contracts for adopter agents writing connector impls
-- **`src/connectors/types.ts`** — authoritative contract interfaces (SkillStore, MemoryStore, LocalModel, McpConnector)
+- **`src/connectors/types.ts`** — authoritative contract interfaces (SkillStore, DataStore, LocalModel, McpConnector)
 - **`src/testing/conformance.ts`** — the per-contract conformance test suites
 
 ## Naming convention

package/examples/connectors/SkillStoreTemplate/README.md

@@ -5,7 +5,7 @@ A skeleton `SkillStore` implementation for adopters writing their own. Not runna
 Use this when you want skillscript skills backed by:
 - A database the bundled impls don't cover (Postgres, MySQL, MongoDB, etc.)
 - A vector store (Pinecone, Weaviate, Qdrant)
-- A memory system (AMP, hosted memory API)
+- A data store backing (memory broker like AMP, hosted memory API, vector DB, etc.)
 - An HTTP CRUD service
 - Anything else with a query/write interface
 

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -138,7 +138,7 @@ export class SkillStoreTemplate implements SkillStore {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async versions(_name: string): Promise<VersionInfo[]> {
     // TODO — return version chain. SQL substrates: SELECT FROM skill_versions
-    // ORDER BY changed_at. MemoryStore-style: query memories with the right tag.
+    // ORDER BY changed_at. DataStore-style: query memories with the right tag.
     throw new Error("TODO: versions() — return VersionInfo[] chronologically.");
   }
 

package/examples/custom-bootstrap.example.ts

@@ -3,8 +3,8 @@
 //
 // **When to write your own bootstrap.** The bundled `bootstrap()` from
 // `skillscript-runtime` wires `FilesystemSkillStore` + `OllamaLocalModel` +
-// `SqliteMemoryStore` + the v0.7.2 bridges. If your deployment uses
-// different substrates (your own memory system, a hosted LLM API, an MCP
+// `SqliteDataStore` + the v0.7.2 bridges. If your deployment uses
+// different substrates (your own data store, a hosted LLM API, an MCP
 // server for agent delivery, etc.), write your own bootstrap rather than
 // modifying the bundled one. Prevents merge conflicts on every upstream
 // release that touches `src/bootstrap.ts`.
@@ -83,17 +83,17 @@ const registry = new Registry();
 const skillStore = new FilesystemSkillStore(config.skillsDir ?? `${HOME}/skills`);
 registry.registerSkillStore("primary", skillStore);
 
-// Wire your own LocalModel, MemoryStore, AgentConnector here. For typed-
+// Wire your own LocalModel, DataStore, AgentConnector here. For typed-
 // contract impls, this is the "case 1" wiring — substrate-portable.
 //   registry.registerLocalModel("default", new MyHostedLlmAdapter(...));
-//   registry.registerMemoryStore("primary", new MyMemoryAdapter(...));
+//   registry.registerDataStore("primary", new MyMemoryAdapter(...));
 //   registry.registerAgentConnector("primary", new MyAgentHarnessAdapter(...));
 
-// Then wire bridges if you want the canonical `$ llm` / `$ memory` surfaces:
-//   import { LocalModelMcpConnector, MemoryStoreMcpConnector } from "skillscript-runtime";
+// Then wire bridges if you want the canonical `$ llm` / `$ data_read` surfaces:
+//   import { LocalModelMcpConnector, DataStoreMcpConnector } from "skillscript-runtime";
 //   registry.registerMcpConnector("llm", new LocalModelMcpConnector(registry.getLocalModel("default")));
-//   const ms = registry.listMemoryStores().find((e) => e.name === "primary");
-//   if (ms !== undefined) registry.registerMcpConnector("memory", new MemoryStoreMcpConnector(ms.instance));
+//   const ms = registry.listDataStores().find((e) => e.name === "primary");
+//   if (ms !== undefined) registry.registerMcpConnector("data_read", new DataStoreMcpConnector(ms.instance));
 
 // Wire any connectors.json instances.
 for (const c of connectors) {

package/examples/onboarding-scaffold/README.md

@@ -6,11 +6,11 @@ A complete adopter-deployment example demonstrating substrate-portable wiring fo
 
 Skillscript's substrate-portability story is conditional: **typed-contract wiring (Case 1)** keeps skills portable across substrates; **MCP-tools wiring (Case 2)** locks skills to a specific substrate. This scaffold is Case 1 end-to-end.
 
-- **MemoryStore** → `FileMemoryStore` (JSON file with simple substring FTS)
+- **DataStore** → `FileDataStore` (JSON file with simple substring FTS)
 - **LocalModel** → `OpenAILocalModel` (HTTP to Chat Completions API)
 - **AgentConnector** → `TmuxShellAgentConnector` (delivers to tmux sessions via `send-keys`)
 
-Each impl conforms to the typed contract from `skillscript-runtime/connectors`. Skills authored against this scaffold use the canonical `$ llm prompt=...` and `$ memory mode=fts query=...` surfaces — *the same calls would work against any other Case-1-wired substrate* (Pinecone, Ollama, Anthropic API, etc.).
+Each impl conforms to the typed contract from `skillscript-runtime/connectors`. Skills authored against this scaffold use the canonical `$ llm prompt=...` and `$ data_read mode=fts query=...` surfaces — *the same calls would work against any other Case-1-wired substrate* (Pinecone, Ollama, Anthropic API, etc.).
 
 ## Quick start
 
@@ -44,7 +44,7 @@ node --loader ts-node/esm bootstrap.ts
 
 | File | Purpose | LOC |
 |---|---|---|
-| `file-memory-store.ts` | `MemoryStore` impl — JSON file substrate | ~95 |
+| `file-data-store.ts` | `DataStore` impl — JSON file substrate | ~95 |
 | `openai-local-model.ts` | `LocalModel` impl — Chat Completions API | ~85 |
 | `tmux-shell-agent-connector.ts` | `AgentConnector` impl — tmux send-keys | ~75 |
 | `bootstrap.ts` | Wiring — Registry, bridges, scheduler, MCP server | ~75 |
@@ -53,7 +53,7 @@ node --loader ts-node/esm bootstrap.ts
 
 ## Two-instance posture
 
-To run this scaffold *alongside* an existing skillscript dev instance, just copy the scaffold to a separate directory with its own `skillscript.config.json` pointing at different `dashboard.port` + `skillsDir` + `memoryDbPath` etc. The `--config <path>` CLI flag selects which config to use; no two instances will collide on disk or port.
+To run this scaffold *alongside* an existing skillscript dev instance, just copy the scaffold to a separate directory with its own `skillscript.config.json` pointing at different `dashboard.port` + `skillsDir` + `dataDbPath` etc. The `--config <path>` CLI flag selects which config to use; no two instances will collide on disk or port.
 
 ```bash
 # dev instance on default port
@@ -67,14 +67,14 @@ skillfile dashboard --config ./adopter.config.json  # contains "dashboard": { "p
 
 For your real deployment, swap each adapter:
 
-- `FileMemoryStore` → your actual memory system (Pinecone, Postgres-pgvector, Obsidian-backed, your in-house store, etc.)
+- `FileDataStore` → your actual data store (Pinecone, Postgres-pgvector, Obsidian-backed, in-house store, memory broker, etc.)
 - `OpenAILocalModel` → your actual LLM (Ollama via the bundled `OllamaLocalModel`, Anthropic via your own adapter, hosted-OpenAI as shown, etc.)
 - `TmuxShellAgentConnector` → your actual agent delivery (webhook POST, named-pipe write, your harness's API, etc.)
 
-The skill bodies don't need to change. `$ llm prompt=...` keeps working; `$ memory mode=fts query=...` keeps working. That's the substrate-portability claim, validated by you wiring different substrates against the same typed contracts.
+The skill bodies don't need to change. `$ llm prompt=...` keeps working; `$ data_read mode=fts query=...` keeps working. That's the substrate-portability claim, validated by you wiring different substrates against the same typed contracts.
 
 ## Where to go next
 
 - **Adopter playbook** — `docs/adopter-playbook.md` walks through Case 1 vs Case 2 wiring patterns
 - **Custom bootstrap walkthrough** — `examples/custom-bootstrap.example.ts` shows registering custom McpConnector classes via `registerConnectorClass`
-- **v0.8.x roadmap** — `$ memory_write` ships in v0.8.x bundled with the auth model. When that lands, extend `FileMemoryStore` with the corresponding `write()` method.
+- **v0.8.x roadmap** — `$ data_write` ships in v0.8.x bundled with the auth model. When that lands, extend `FileDataStore` with the corresponding `write()` method.

package/examples/onboarding-scaffold/bootstrap.ts

@@ -4,8 +4,8 @@
 // Copy this file into your deployment and modify substrate choices to
 // match your environment. The shape is:
 //   1. Construct a Registry
-//   2. Register your substrate impls (SkillStore + LocalModel + MemoryStore + AgentConnector)
-//   3. Wire bridges so canonical `$ llm` / `$ memory` dispatch works
+//   2. Register your substrate impls (SkillStore + LocalModel + DataStore + AgentConnector)
+//   3. Wire bridges so canonical `$ llm` / `$ data_read` dispatch works
 //   4. Load connectors.json + skillscript.config.json
 //   5. Wire scheduler + MCP server
 //   6. Start
@@ -20,15 +20,15 @@ import {
 import { Scheduler } from "skillscript-runtime/scheduler";
 import { FilesystemTraceStore } from "skillscript-runtime/trace";
 import { McpServer } from "skillscript-runtime/mcp-server";
-// Note: LocalModelMcpConnector + MemoryStoreMcpConnector are bridge classes
+// Note: LocalModelMcpConnector + DataStoreMcpConnector are bridge classes
 // already exported from skillscript-runtime/connectors. They wrap any
 // typed-contract impl as an MCP-dispatchable connector.
 import {
   LocalModelMcpConnector,
-  MemoryStoreMcpConnector,
+  DataStoreMcpConnector,
 } from "skillscript-runtime/connectors";
 
-import { FileMemoryStore } from "./file-memory-store.js";
+import { FileDataStore } from "./file-data-store.js";
 import { OpenAILocalModel } from "./openai-local-model.js";
 import { TmuxShellAgentConnector } from "./tmux-shell-agent-connector.js";
 
@@ -44,10 +44,10 @@ const skillStore = new FilesystemSkillStore(config.skillsDir ?? `${HOME}/skills`
 registry.registerSkillStore("primary", skillStore);
 
 // File-backed memory at $SKILLSCRIPT_HOME/memory.json
-const memoryStore = new FileMemoryStore({
-  filePath: config.memoryDbPath ?? `${HOME}/memory.json`,
+const dataStore = new FileDataStore({
+  filePath: config.dataDbPath ?? `${HOME}/memory.json`,
 });
-registry.registerMemoryStore("primary", memoryStore);
+registry.registerDataStore("primary", dataStore);
 
 // OpenAI LLM — reads OPENAI_API_KEY from env.
 const openai = new OpenAILocalModel({ defaultModel: "gpt-4o-mini" });
@@ -63,10 +63,10 @@ const agentConnector = new TmuxShellAgentConnector({
 });
 registry.registerAgentConnector("primary", agentConnector);
 
-// Step 3: wire bridges so `$ llm` / `$ memory` dispatch through the
+// Step 3: wire bridges so `$ llm` / `$ data_read` dispatch through the
 // adopter substrates above (case 1 typed-contract wiring — portable).
 registry.registerMcpConnector("llm", new LocalModelMcpConnector(openai));
-registry.registerMcpConnector("memory", new MemoryStoreMcpConnector(memoryStore));
+registry.registerMcpConnector("data_read", new DataStoreMcpConnector(dataStore));
 
 // Step 4: wire connectors.json instances (adopter-defined MCP servers).
 for (const c of connectors) {

package/examples/onboarding-scaffold/{file-memory-store.ts → file-data-store.ts}

@@ -1,40 +1,40 @@
-// Onboarding scaffold: file-backed MemoryStore. v0.7.3.
+// Onboarding scaffold: file-backed DataStore. v0.7.3.
 //
 // JSON file as the substrate; simple JS substring + token match for "fts"
 // queries; reranks by recency. Adopters copy this file and modify for
 // their concrete substrate (e.g., swap the JSON file for a Postgres
 // table, the substring match for actual full-text search, etc.).
 //
-// **Scope.** Read-only `query()` per the v0.7.2 MemoryStore contract.
+// **Scope.** Read-only `query()` per the v0.7.2 DataStore contract.
 // `write()` is deferred to v0.8.x bundled with the auth model — when
 // that lands, extend this file with the matching `write()` method.
 
 import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import type {
-  MemoryStore,
-  MemoryWrite,
-  MemoryWriteRecord,
-  PortableMemory,
+  DataStore,
+  DataWrite,
+  DataWriteRecord,
+  PortableData,
   QueryFilters,
   ManifestInfo,
   StaticCapabilities,
 } from "skillscript-runtime/connectors";
 
-export interface FileMemoryStoreConfig {
+export interface FileDataStoreConfig {
   /** Absolute path to the JSON file holding the memory array. */
   filePath: string;
 }
 
-interface FileMemoryRecord extends PortableMemory {
-  /** Optional substrate-specific fields go in `metadata`; everything top-level matches PortableMemory. */
+interface FileMemoryRecord extends PortableData {
+  /** Optional substrate-specific fields go in `metadata`; everything top-level matches PortableData. */
 }
 
-export class FileMemoryStore implements MemoryStore {
+export class FileDataStore implements DataStore {
   static staticCapabilities(): StaticCapabilities {
     return {
-      connector_type: "memory_store",
-      implementation: "FileMemoryStore",
+      connector_type: "data_store",
+      implementation: "FileDataStore",
       contract_version: "1.0.0",
       features: {
         supports_fts: true,
@@ -44,9 +44,9 @@ export class FileMemoryStore implements MemoryStore {
     };
   }
 
-  constructor(private readonly config: FileMemoryStoreConfig) {}
+  constructor(private readonly config: FileDataStoreConfig) {}
 
-  async query(filters: QueryFilters): Promise<PortableMemory[]> {
+  async query(filters: QueryFilters): Promise<PortableData[]> {
     const records = this.loadFile();
     const queryTerms = filters.query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
 
@@ -71,7 +71,7 @@ export class FileMemoryStore implements MemoryStore {
     return scored.slice(0, filters.limit).map((s) => s.record);
   }
 
-  async write(entry: MemoryWrite): Promise<MemoryWriteRecord> {
+  async write(entry: DataWrite): Promise<DataWriteRecord> {
     const records = this.loadFile();
     const id = randomUUID();
     const created_at = Math.floor(Date.now() / 1000);
@@ -102,7 +102,7 @@ export class FileMemoryStore implements MemoryStore {
     return {
       capabilities_version: "1",
       manifest: {
-        kind: "file-memory-store",
+        kind: "file-data-store",
         file_path: this.config.filePath,
         record_count: this.loadFile().length,
         supports_write: true,
@@ -116,11 +116,11 @@ export class FileMemoryStore implements MemoryStore {
       const raw = readFileSync(this.config.filePath, "utf8");
       const parsed: unknown = JSON.parse(raw);
       if (!Array.isArray(parsed)) {
-        throw new Error(`FileMemoryStore: '${this.config.filePath}' top-level must be an array of memory records.`);
+        throw new Error(`FileDataStore: '${this.config.filePath}' top-level must be an array of memory records.`);
       }
       return parsed as FileMemoryRecord[];
     } catch (err) {
-      throw new Error(`FileMemoryStore: failed to read '${this.config.filePath}': ${(err as Error).message}`);
+      throw new Error(`FileDataStore: failed to read '${this.config.filePath}': ${(err as Error).message}`);
     }
   }
 }

package/examples/skillscripts/classify-support-ticket.skill.md

@@ -15,16 +15,16 @@ route:
     needs: severity_check
     if ${CATEGORY|trim} == "sev-1":
         emit(text="PAGE: sev-1 ticket ${TICKET_ID} - ${TICKET_TEXT}")
-        $ memorystore.write summary="sev-1 ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","page"]
+        $ datastore.write summary="sev-1 ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","page"]
     elif ${IS_SEV1|trim} == "yes":
         emit(text="PAGE: classifier said ${CATEGORY|trim} but severity-check flagged this as sev-1: ${TICKET_ID}")
-        $ memorystore.write summary="sev-1 escalation ${TICKET_ID}" detail="category=${CATEGORY|trim} but severity-check=yes" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","disagreement"]
+        $ datastore.write summary="sev-1 escalation ${TICKET_ID}" detail="category=${CATEGORY|trim} but severity-check=yes" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","disagreement"]
     elif ${CATEGORY|trim} == "billing":
         $set TAG_FOR = "finance"
         emit(text="Tagged for ${TAG_FOR} review: ${TICKET_ID}")
-        $ memorystore.write summary="billing ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=common vault=private domain_tags=["support","billing"]
+        $ datastore.write summary="billing ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=common vault=private domain_tags=["support","billing"]
     else:
         $ llm prompt="Draft a polite acknowledgment reply for this support ticket. Two short sentences. No greeting, no sign-off.\n\n${TICKET_TEXT}" model=qwen maxTokens=150 -> DRAFT
-        $ memorystore.write summary="support draft ${TICKET_ID}" detail="${DRAFT|trim}" knowledge_type=common vault=private domain_tags=["support","draft"]
+        $ datastore.write summary="support draft ${TICKET_ID}" detail="${DRAFT|trim}" knowledge_type=common vault=private domain_tags=["support","draft"]
 
 default: route

package/examples/skillscripts/doc-qa-with-citations.skill.md

@@ -5,7 +5,7 @@
 # Output: text
 
 answer:
-    $ memory mode=rerank query="${QUESTION}" limit=${K} -> HITS (fallback: [])
+    $ data_read mode=rerank query="${QUESTION}" limit=${K} -> HITS (fallback: [])
     $ llm prompt="Answer the question using ONLY the supplied passages. Cite each claim inline as [id:<memory-id>]. Question: ${QUESTION}. Passages: ${HITS|json}" maxTokens=900 -> RESPONSE
     emit(text="${RESPONSE}")
 

package/examples/skillscripts/feedback-sentiment-scan.skill.md

@@ -6,10 +6,10 @@
 # Output: agent: support-lead
 
 fetch_new:
-    $ memory mode=fts query="customer feedback" limit=${SCAN_LIMIT} created_after=${EVENT.fired_at_unix} -> FEEDBACK
+    $ data_read mode=fts query="customer feedback" limit=${SCAN_LIMIT} created_after=${EVENT.fired_at_unix} -> FEEDBACK
 
 fetch_seen:
-    $ memory mode=fts query="sentiment-scan seen marker" limit=200 domain_tags=["sentiment-scan-seen"] -> SEEN_MARKERS
+    $ data_read mode=fts query="sentiment-scan seen marker" limit=200 domain_tags=["sentiment-scan-seen"] -> SEEN_MARKERS
 
 classify_and_emit:
     needs: fetch_new, fetch_seen
@@ -23,6 +23,6 @@ classify_and_emit:
                 emit(text="- FRUSTRATED [${F.id|trim}] ${F.summary}")
             elif ${VERDICT|trim} == "blocking":
                 emit(text="- BLOCKING [${F.id|trim}] ${F.summary}")
-            $ memorystore.write summary="sentiment-scan seen ${F.id|trim}" detail="verdict=${VERDICT|trim} on ${EVENT.fired_at_unix}" knowledge_type=common vault=private domain_tags=["sentiment-scan-seen"] expires_at=${EVENT.fired_at_plus_7d_unix}
+            $ datastore.write summary="sentiment-scan seen ${F.id|trim}" detail="verdict=${VERDICT|trim} on ${EVENT.fired_at_unix}" knowledge_type=common vault=private domain_tags=["sentiment-scan-seen"] expires_at=${EVENT.fired_at_plus_7d_unix}
 
 default: classify_and_emit

package/examples/skillscripts/hello.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-29T21:43:48.999Z",
+  "compiled_at": "2026-05-30T14:28:14.260Z",
   "source_skill": {
     "name": "hello"
   },

package/examples/skillscripts/morning-brief.skill.md

@@ -1,6 +1,6 @@
 # Skill: morning-brief
 # Status: Approved v1:037c18af
-# Description: Compose a daily morning brief from calendar, mailbox, and overnight memory writes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc.
+# Description: Compose a daily morning brief from calendar, mailbox, and overnight data writes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc.
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *
 # OnError: morning-brief-degraded
@@ -10,10 +10,10 @@ calendar:
     $ calendar.list_events horizon_hours=${BRIEF_HORIZON_HOURS} -> EVENTS
 
 mailbox:
-    $ memory mode=fts query="addressed:${AGENT} created_after:${EVENT.fired_at_unix}" limit=10 -> MAIL
+    $ data_read mode=fts query="addressed:${AGENT} created_after:${EVENT.fired_at_unix}" limit=10 -> MAIL
 
 overnight:
-    $ memory mode=rerank query="overnight writes since:${EVENT.fired_at_plus_1d_unix}" limit=15 -> NOTES
+    $ data_read mode=rerank query="overnight writes since:${EVENT.fired_at_plus_1d_unix}" limit=15 -> NOTES
 
 compose: needs: calendar, mailbox, overnight
     $ llm prompt="Compose a concise morning brief. Calendar: ${EVENTS|json}. Mailbox: ${MAIL|json}. Overnight notes: ${NOTES|json}. Three sections, six bullets max each." model=qwen maxTokens=1200 -> BRIEF

package/examples/skillscripts/service-health-watch.skill.md

@@ -10,7 +10,7 @@ probe:
         shell(command="curl -s -o /dev/null -w \"%{http_code} %{time_total}\" https://status.internal/${SVC|url}") -> RAW
         $ llm prompt="From the line '${RAW|trim}' (http_code time_seconds), and budget ${LATENCY_BUDGET_MS} ms, answer ok or degraded only." -> STATUS
         if ${STATUS|trim} == "degraded":
-            $ memorystore.write summary="service degradation: ${SVC}" detail="probe at ${NOW}: ${RAW|trim}" domain_tags=[ops, service-health, degraded:${SVC}] vault=private knowledge_type=common expires_at=${EVENT.fired_at_plus_1d_unix} -> ACK
+            $ datastore.write summary="service degradation: ${SVC}" detail="probe at ${NOW}: ${RAW|trim}" domain_tags=[ops, service-health, degraded:${SVC}] vault=private knowledge_type=common expires_at=${EVENT.fired_at_plus_1d_unix} -> ACK
             emit(text="${SVC} degraded — wrote signal")
         else:
             emit(text="${SVC} ok")