yai-dev · yai-dev · Apr 13, 2026 · Apr 13, 2026
diff --git a/.changeset/storage-abstraction-postgres.md b/.changeset/storage-abstraction-postgres.md
diff --git a/packages/app/CHANGELOG.md b/packages/app/CHANGELOG.md
@@ -1,5 +1,61 @@
 # @agentrail/app
 
+## 0.7.0
+
+### Minor Changes
+
+- [#143](https://github.com/yai-dev/agentrail/pull/143) [`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32) Thanks [@yai-dev](https://github.com/yai-dev)! - **Storage Abstraction + Memo FS + PostgreSQL reference implementation ([#69](https://github.com/yai-dev/agentrail/issues/69))**
+
+  This release completes the Pre-GA storage contract consolidation and ships the `@agentrail/storage-postgres` reference package.
+
+  ### `@agentrail/core` — breaking shape changes + new optional methods
+  - `MemoryIndex` no longer contains `sessionDir` or `userDir` host-absolute paths. The `entries[].path` field now stores the canonical `/workspace/memo/…` path directly.
+  - `AgentrailSessionStore` gains five new **optional** methods for memo-document and tool-result-artifact persistence:
+    - `readMemoryDocument(tenantId, ownerId, scope, name)`
+    - `writeMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `appendMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `readToolResultArtifact(sessionRef, toolCallId)`
+    - `writeToolResultArtifact(sessionRef, toolCallId, content)`
+  - New types exported: `MemoDocumentScope`, `MemoDocumentName`
+
+  ### `@agentrail/capabilities` — new exports + breaking signature
+  - `OrchestrationPersistence` gains two new required methods: `loadAgentHistory(agentId)` and `writeAgentHistory(agentId, history)`.
+  - `DefaultCapabilityContextOptions.compactMessages` signature updated: `sessionDir` replaced by `writeToolResultArtifact` callback injection.
+  - New public exports: `OrchestrationMailboxEvent`, `OrchestrationSnapshot`, `recoverOrchestrationState`.
+  - `WorkerInitMessage` gains an optional `storageConfig` field for sub-agent worker initialization.
+
+  ### `@agentrail/app` — breaking API surface changes
+  - `CreateAgentAppOptions` gains: `traceStoreFactory`, `createOrchestrationPersistence`, `createWorkerStorageConfig`, and `inspector` (now accepts `true | InspectorDataSource`).
+  - `createInspectorRoute` now accepts `InspectorDataSource | string` (string is deprecated backward-compat path; direct `dataDir` strings will be removed in a future release).
+  - `UserMemoryConsolidationService` constructor signature changed from `(sessionManager, dataDir, config)` to `(store: AgentrailSessionStore, sessionLister: UserSessionLister, dataDir, config)`.
+  - New `UserSessionLister` interface exported.
+  - New `InspectorDataSource`, `InspectorSessionItem`, `SessionTraceStore` types exported.
+  - New `createFilesystemInspectorDataSource(dataDir)` function exported.
+  - `compactToolResults` now prefers `writeToolResultArtifact` from the session store when available.
+  - Pure compaction helpers exported: `computeCompactionSplit`, `buildCompactionMessage`, `buildCompactionNotesEntry`.
+
+  ### `@agentrail/storage-postgres` — new package
+
+  PostgreSQL reference implementation for all Agentrail storage contracts:
+  - `PostgresSessionStore` — full `AgentrailSessionStore` including memo documents and tool-result artifacts.
+  - `PostgresSessionTraceStore` + `createPostgresSessionTraceStore` factory.
+  - `PostgresOrchestrationPersistence` + `createPostgresOrchestrationPersistence` factory (includes agent history).
+  - `PostgresInspectorDataSource` — reads session list, messages, trace envelopes, and orchestration state from PostgreSQL without any filesystem dependency.
+  - `buildSchemaDDL(schema?)` — returns idempotent DDL to create all required tables.
+  - `createSqlClient(options)` — creates a `postgres` (postgres.js) connection pool.
+
+  **Upgrade notes:**
+  1. If you implement `AgentrailSessionStore`, the new optional methods do not need to be implemented immediately; the runtime falls back gracefully. However, implementing them is required to use the postgres backend.
+  2. If you implement `OrchestrationPersistence`, you must add `loadAgentHistory` and `writeAgentHistory`.
+  3. Replace `createInspectorRoute(dataDir)` with `createInspectorRoute(createFilesystemInspectorDataSource(dataDir))` when providing a custom `InspectorDataSource`.
+  4. `UserMemoryConsolidationService` callers must provide a `UserSessionLister` (the default `SessionManager` now implements this interface).
+
+### Patch Changes
+
+- Updated dependencies [[`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32)]:
+  - @agentrail/core@0.7.0
+  - @agentrail/capabilities@0.4.0
+
 ## 0.6.0
 
 ### Minor Changes

diff --git a/packages/app/package.json b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/app",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "App-layer hosting, profiles, session management, and createAgentApp for Agentrail.",
   "type": "module",
   "files": [

diff --git a/packages/capabilities/CHANGELOG.md b/packages/capabilities/CHANGELOG.md
@@ -1,5 +1,60 @@
 # @agentrail/capabilities
 
+## 0.4.0
+
+### Minor Changes
+
+- [#143](https://github.com/yai-dev/agentrail/pull/143) [`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32) Thanks [@yai-dev](https://github.com/yai-dev)! - **Storage Abstraction + Memo FS + PostgreSQL reference implementation ([#69](https://github.com/yai-dev/agentrail/issues/69))**
+
+  This release completes the Pre-GA storage contract consolidation and ships the `@agentrail/storage-postgres` reference package.
+
+  ### `@agentrail/core` — breaking shape changes + new optional methods
+  - `MemoryIndex` no longer contains `sessionDir` or `userDir` host-absolute paths. The `entries[].path` field now stores the canonical `/workspace/memo/…` path directly.
+  - `AgentrailSessionStore` gains five new **optional** methods for memo-document and tool-result-artifact persistence:
+    - `readMemoryDocument(tenantId, ownerId, scope, name)`
+    - `writeMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `appendMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `readToolResultArtifact(sessionRef, toolCallId)`
+    - `writeToolResultArtifact(sessionRef, toolCallId, content)`
+  - New types exported: `MemoDocumentScope`, `MemoDocumentName`
+
+  ### `@agentrail/capabilities` — new exports + breaking signature
+  - `OrchestrationPersistence` gains two new required methods: `loadAgentHistory(agentId)` and `writeAgentHistory(agentId, history)`.
+  - `DefaultCapabilityContextOptions.compactMessages` signature updated: `sessionDir` replaced by `writeToolResultArtifact` callback injection.
+  - New public exports: `OrchestrationMailboxEvent`, `OrchestrationSnapshot`, `recoverOrchestrationState`.
+  - `WorkerInitMessage` gains an optional `storageConfig` field for sub-agent worker initialization.
+
+  ### `@agentrail/app` — breaking API surface changes
+  - `CreateAgentAppOptions` gains: `traceStoreFactory`, `createOrchestrationPersistence`, `createWorkerStorageConfig`, and `inspector` (now accepts `true | InspectorDataSource`).
+  - `createInspectorRoute` now accepts `InspectorDataSource | string` (string is deprecated backward-compat path; direct `dataDir` strings will be removed in a future release).
+  - `UserMemoryConsolidationService` constructor signature changed from `(sessionManager, dataDir, config)` to `(store: AgentrailSessionStore, sessionLister: UserSessionLister, dataDir, config)`.
+  - New `UserSessionLister` interface exported.
+  - New `InspectorDataSource`, `InspectorSessionItem`, `SessionTraceStore` types exported.
+  - New `createFilesystemInspectorDataSource(dataDir)` function exported.
+  - `compactToolResults` now prefers `writeToolResultArtifact` from the session store when available.
+  - Pure compaction helpers exported: `computeCompactionSplit`, `buildCompactionMessage`, `buildCompactionNotesEntry`.
+
+  ### `@agentrail/storage-postgres` — new package
+
+  PostgreSQL reference implementation for all Agentrail storage contracts:
+  - `PostgresSessionStore` — full `AgentrailSessionStore` including memo documents and tool-result artifacts.
+  - `PostgresSessionTraceStore` + `createPostgresSessionTraceStore` factory.
+  - `PostgresOrchestrationPersistence` + `createPostgresOrchestrationPersistence` factory (includes agent history).
+  - `PostgresInspectorDataSource` — reads session list, messages, trace envelopes, and orchestration state from PostgreSQL without any filesystem dependency.
+  - `buildSchemaDDL(schema?)` — returns idempotent DDL to create all required tables.
+  - `createSqlClient(options)` — creates a `postgres` (postgres.js) connection pool.
+
+  **Upgrade notes:**
+  1. If you implement `AgentrailSessionStore`, the new optional methods do not need to be implemented immediately; the runtime falls back gracefully. However, implementing them is required to use the postgres backend.
+  2. If you implement `OrchestrationPersistence`, you must add `loadAgentHistory` and `writeAgentHistory`.
+  3. Replace `createInspectorRoute(dataDir)` with `createInspectorRoute(createFilesystemInspectorDataSource(dataDir))` when providing a custom `InspectorDataSource`.
+  4. `UserMemoryConsolidationService` callers must provide a `UserSessionLister` (the default `SessionManager` now implements this interface).
+
+### Patch Changes
+
+- Updated dependencies [[`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32)]:
+  - @agentrail/core@0.7.0
+
 ## 0.3.0
 
 ### Minor Changes

diff --git a/packages/capabilities/package.json b/packages/capabilities/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/capabilities",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "App-layer capability descriptors: filesystem, browser, knowledge, skills, orchestration, and memory for Agentrail.",
   "type": "module",
   "files": [

diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @agentrail/cli
 
+## 0.2.6
+
+### Patch Changes
+
+- Updated dependencies [[`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32)]:
+  - @agentrail/app@0.7.0
+
 ## 0.2.5
 
 ### Patch Changes

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Official CLI for Agentrail — scaffold, diagnose, and validate your agent applications",
   "type": "module",
   "main": "./dist/index.js",

diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,5 +1,55 @@
 # @agentrail/core
 
+## 0.7.0
+
+### Minor Changes
+
+- [#143](https://github.com/yai-dev/agentrail/pull/143) [`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32) Thanks [@yai-dev](https://github.com/yai-dev)! - **Storage Abstraction + Memo FS + PostgreSQL reference implementation ([#69](https://github.com/yai-dev/agentrail/issues/69))**
+
+  This release completes the Pre-GA storage contract consolidation and ships the `@agentrail/storage-postgres` reference package.
+
+  ### `@agentrail/core` — breaking shape changes + new optional methods
+  - `MemoryIndex` no longer contains `sessionDir` or `userDir` host-absolute paths. The `entries[].path` field now stores the canonical `/workspace/memo/…` path directly.
+  - `AgentrailSessionStore` gains five new **optional** methods for memo-document and tool-result-artifact persistence:
+    - `readMemoryDocument(tenantId, ownerId, scope, name)`
+    - `writeMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `appendMemoryDocument(tenantId, ownerId, scope, name, content)`
+    - `readToolResultArtifact(sessionRef, toolCallId)`
+    - `writeToolResultArtifact(sessionRef, toolCallId, content)`
+  - New types exported: `MemoDocumentScope`, `MemoDocumentName`
+
+  ### `@agentrail/capabilities` — new exports + breaking signature
+  - `OrchestrationPersistence` gains two new required methods: `loadAgentHistory(agentId)` and `writeAgentHistory(agentId, history)`.
+  - `DefaultCapabilityContextOptions.compactMessages` signature updated: `sessionDir` replaced by `writeToolResultArtifact` callback injection.
+  - New public exports: `OrchestrationMailboxEvent`, `OrchestrationSnapshot`, `recoverOrchestrationState`.
+  - `WorkerInitMessage` gains an optional `storageConfig` field for sub-agent worker initialization.
+
+  ### `@agentrail/app` — breaking API surface changes
+  - `CreateAgentAppOptions` gains: `traceStoreFactory`, `createOrchestrationPersistence`, `createWorkerStorageConfig`, and `inspector` (now accepts `true | InspectorDataSource`).
+  - `createInspectorRoute` now accepts `InspectorDataSource | string` (string is deprecated backward-compat path; direct `dataDir` strings will be removed in a future release).
+  - `UserMemoryConsolidationService` constructor signature changed from `(sessionManager, dataDir, config)` to `(store: AgentrailSessionStore, sessionLister: UserSessionLister, dataDir, config)`.
+  - New `UserSessionLister` interface exported.
+  - New `InspectorDataSource`, `InspectorSessionItem`, `SessionTraceStore` types exported.
+  - New `createFilesystemInspectorDataSource(dataDir)` function exported.
+  - `compactToolResults` now prefers `writeToolResultArtifact` from the session store when available.
+  - Pure compaction helpers exported: `computeCompactionSplit`, `buildCompactionMessage`, `buildCompactionNotesEntry`.
+
+  ### `@agentrail/storage-postgres` — new package
+
+  PostgreSQL reference implementation for all Agentrail storage contracts:
+  - `PostgresSessionStore` — full `AgentrailSessionStore` including memo documents and tool-result artifacts.
+  - `PostgresSessionTraceStore` + `createPostgresSessionTraceStore` factory.
+  - `PostgresOrchestrationPersistence` + `createPostgresOrchestrationPersistence` factory (includes agent history).
+  - `PostgresInspectorDataSource` — reads session list, messages, trace envelopes, and orchestration state from PostgreSQL without any filesystem dependency.
+  - `buildSchemaDDL(schema?)` — returns idempotent DDL to create all required tables.
+  - `createSqlClient(options)` — creates a `postgres` (postgres.js) connection pool.
+
+  **Upgrade notes:**
+  1. If you implement `AgentrailSessionStore`, the new optional methods do not need to be implemented immediately; the runtime falls back gracefully. However, implementing them is required to use the postgres backend.
+  2. If you implement `OrchestrationPersistence`, you must add `loadAgentHistory` and `writeAgentHistory`.
+  3. Replace `createInspectorRoute(dataDir)` with `createInspectorRoute(createFilesystemInspectorDataSource(dataDir))` when providing a custom `InspectorDataSource`.
+  4. `UserMemoryConsolidationService` callers must provide a `UserSessionLister` (the default `SessionManager` now implements this interface).
+
 ## 0.6.0
 
 ### Minor Changes

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Core runtime primitives, agent loop, and session contracts for Agentrail.",
   "type": "module",
   "files": [

diff --git a/packages/create-agentrail-app/CHANGELOG.md b/packages/create-agentrail-app/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @agentrail/create-agentrail-app
 
+## 0.2.6
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @agentrail/cli@0.2.6
+
 ## 0.2.5
 
 ### Patch Changes

diff --git a/packages/create-agentrail-app/package.json b/packages/create-agentrail-app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/create-agentrail-app",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Create a new Agentrail application from a template (delegates to @agentrail/cli)",
   "type": "module",
   "bin": {

diff --git a/packages/deep-research/CHANGELOG.md b/packages/deep-research/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @agentrail/deep-research
 
+## 0.0.14
+
+### Patch Changes
+
+- Updated dependencies [[`f5a4d2e`](https://github.com/yai-dev/agentrail/commit/f5a4d2e24586425f054d35071c76b47078e3cd32)]:
+  - @agentrail/core@0.7.0
+  - @agentrail/capabilities@0.4.0
+
 ## 0.0.13
 
 ### Patch Changes

diff --git a/packages/deep-research/package.json b/packages/deep-research/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/deep-research",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Reusable Deep Research workflow package for Agentrail examples.",
   "type": "module",
   "files": [