Add rebuildable vector memory and harden migration surfaces

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -11,7 +11,7 @@ body:
     id: version
     attributes:
       label: Runtime version
-      placeholder: 0.3.0-alpha.1
+      placeholder: 0.3.0-alpha.2
     validations:
       required: true
   - type: dropdown

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ permissions:
   contents: read
 
 env:
-  CI_PACKAGE_VERSION: 0.3.0-alpha.1
+  CI_PACKAGE_VERSION: 0.3.0-alpha.2
 
 jobs:
   dotnet:
@@ -74,7 +74,7 @@ jobs:
         shell: pwsh
         run: |
           $archive = Join-Path $env:RUNNER_TEMP 'godot.zip'
-          Invoke-WebRequest -Uri 'https://github.com/godotengine/godot/releases/download/4.7.1-stable/Godot_v4.7.1-stable_mono_win64.zip' -OutFile $archive
+          Invoke-WebRequest -Uri 'https://github.com/godotengine/godot/releases/download/4.7.1-stable/Godot_v4.7.1-stable_mono_win64.zip' -OutFile $archive -MaximumRetryCount 4 -RetryIntervalSec 5
           $actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA512).Hash.ToLowerInvariant()
           $expected = 'aa04876c7932c2e6807233e6908da4045e904781a83dc3c793c34ba71c9f66292eb4da82aa55a6b8694fccf856f8c244c7709cfba20405066445daf9c2749b71'
           if ($actual -ne $expected) { throw 'Godot archive checksum mismatch.' }

.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
       version:
         description: Semantic version for the artifacts
         required: true
-        default: 0.3.0-alpha.1
+        default: 0.3.0-alpha.2
       publish:
         description: Publish NuGet packages and the GitHub release
         required: true
@@ -65,7 +65,7 @@ jobs:
         run: |
           $archive = Join-Path $env:RUNNER_TEMP 'godot.zip'
           $root = Join-Path $env:RUNNER_TEMP 'godot'
-          Invoke-WebRequest -Uri 'https://github.com/godotengine/godot/releases/download/4.7.1-stable/Godot_v4.7.1-stable_mono_win64.zip' -OutFile $archive
+          Invoke-WebRequest -Uri 'https://github.com/godotengine/godot/releases/download/4.7.1-stable/Godot_v4.7.1-stable_mono_win64.zip' -OutFile $archive -MaximumRetryCount 4 -RetryIntervalSec 5
           $actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA512).Hash.ToLowerInvariant()
           $expected = 'aa04876c7932c2e6807233e6908da4045e904781a83dc3c793c34ba71c9f66292eb4da82aa55a6b8694fccf856f8c244c7709cfba20405066445daf9c2749b71'
           if ($actual -ne $expected) { throw 'Godot archive checksum mismatch.' }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0-alpha.2
+
+- Add the optional `OpenGameAgent.Memory` package with a model-agnostic embedding provider contract, authoritative-save verification, rebuildable local vector indexes, hybrid lexical/vector recall, structured diagnostics, and game-time-aware reranking.
+- Add deterministic authoritative memory snapshots for in-memory and local-file stores so derived indexes can be rebuilt explicitly after embedding model or preprocessing changes.
+- Document local source references and game-provided local embedding integration, including BGE-M3-compatible query/document adapters and save boundaries.
+- Make generated memory, delegation, structured-interaction, large-result artifact, external-knowledge artifact, and MCP artifact IDs stable across fresh runtime attempts, and keep engine project lock files aligned with the release version.
+
 ## 0.3.0-alpha.1
 
 - Introduce a compact stateful streaming Agent kernel with typed content, validated tools, steering, follow-up, hooks, cancellation, transcript integrity checks, bounded concurrency, and explicit failure results.

CITATION.cff

@@ -8,7 +8,7 @@ authors:
 repository-code: "https://github.com/EricSun0218/OpenGameAgent"
 url: "https://github.com/EricSun0218/OpenGameAgent"
 license: "Apache-2.0"
-version: "0.3.0-alpha.1"
+version: "0.3.0-alpha.2"
 keywords:
   - game AI
   - AI agents

Directory.Build.props

@@ -8,7 +8,7 @@
     <PathMap>$(MSBuildThisFileDirectory)=/_/</PathMap>
     <DebugType Condition="'$(Configuration)' == 'Release'">embedded</DebugType>
     <VersionPrefix>0.3.0</VersionPrefix>
-    <VersionSuffix>alpha.1</VersionSuffix>
+    <VersionSuffix>alpha.2</VersionSuffix>
     <Authors>Eric Sun</Authors>
     <Company>Eric Sun</Company>
     <Copyright>Copyright © 2026 Eric Sun</Copyright>

OpenGameAgent.sln

@@ -98,6 +98,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenGameAgent.Plugins", "sr
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenGameAgent.Plugins.Tests", "tests\OpenGameAgent.Plugins.Tests\OpenGameAgent.Plugins.Tests.csproj", "{5697E98C-2249-4D4C-894B-CB0A8732238E}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenGameAgent.Memory", "src\OpenGameAgent.Memory\OpenGameAgent.Memory.csproj", "{00AE7836-01FA-4151-A38A-8263D9164A75}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenGameAgent.Memory.Tests", "tests\OpenGameAgent.Memory.Tests\OpenGameAgent.Memory.Tests.csproj", "{5E8B096B-DD5F-4463-B841-7675F560B52D}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -288,6 +292,14 @@ Global
 		{5697E98C-2249-4D4C-894B-CB0A8732238E}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5697E98C-2249-4D4C-894B-CB0A8732238E}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{5697E98C-2249-4D4C-894B-CB0A8732238E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{00AE7836-01FA-4151-A38A-8263D9164A75}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{00AE7836-01FA-4151-A38A-8263D9164A75}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{00AE7836-01FA-4151-A38A-8263D9164A75}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{00AE7836-01FA-4151-A38A-8263D9164A75}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5E8B096B-DD5F-4463-B841-7675F560B52D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5E8B096B-DD5F-4463-B841-7675F560B52D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5E8B096B-DD5F-4463-B841-7675F560B52D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5E8B096B-DD5F-4463-B841-7675F560B52D}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{01759D73-7B80-47A2-9D7D-154CC64C6851} = {EA3AF59A-9A1C-4197-B2A3-F93894D131B8}
@@ -320,5 +332,7 @@ Global
 		{9CFA2749-BE81-45DE-A07B-CC005F87C5BD} = {86AE6217-BFEE-4349-945A-70ECEC211437}
 		{01A9B761-5567-4C17-B6ED-574B4089D413} = {EA3AF59A-9A1C-4197-B2A3-F93894D131B8}
 		{5697E98C-2249-4D4C-894B-CB0A8732238E} = {86AE6217-BFEE-4349-945A-70ECEC211437}
+		{00AE7836-01FA-4151-A38A-8263D9164A75} = {EA3AF59A-9A1C-4197-B2A3-F93894D131B8}
+		{5E8B096B-DD5F-4463-B841-7675F560B52D} = {86AE6217-BFEE-4349-945A-70ECEC211437}
 	EndGlobalSection
 EndGlobal

README.md

@@ -12,7 +12,7 @@ OpenGameAgent brings the small, composable agent-kernel model to game developmen
 
 Inputs are bounded JSON. They may represent dialogue, combat observations, simulation ticks, UI events, plans, sensor state, or any other game-owned data; natural language is optional. No model is bundled. Cloud and local API endpoints are both supported.
 
-> Current version: `0.3.0-alpha.1`. Public APIs can change before `1.0`.
+> Current version: `0.3.0-alpha.2`. Public APIs can change before `1.0`.
 
 The kernel boundary is intentionally small and designed to stabilize early. New game-specific capabilities should normally arrive as extensions, tools, policies, workflows, or game-owned services instead of expanding the model/tool loop.
 
@@ -21,7 +21,8 @@ The kernel boundary is intentionally small and designed to stabilize early. New
 Install the complete game runtime from NuGet:
 
 ```bash
-dotnet add package OpenGameAgent --version 0.3.0-alpha.1
+dotnet add package OpenGameAgent --version 0.3.0-alpha.2
+dotnet add package OpenGameAgent.Memory --version 0.3.0-alpha.2 # optional semantic memory
 ```
 
 The kernel, persistence, providers, and engine-compatible client are also published as separate `OpenGameAgent.*` packages. Godot, Unity, and portable server archives are available on the [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) page. See [Getting started](docs/getting-started.md) and [Engine integration](docs/engine-integration.md) before connecting a game.
@@ -38,6 +39,7 @@ OpenGameAgent keeps the reusable agent machinery independent from the game while
 - per-actor serialization with bounded cross-actor concurrency;
 - journaled action intents and authoritative game receipts;
 - game-time memory filtering, expiry, and optional custom ranking;
+- optional local/remote embeddings, rebuildable vector indexes, and lexical/vector hybrid recall;
 - skills selected by input type and available tools;
 - recurring game-time triggers and persistent actor mailboxes;
 - a typed extension API for tools, skills, routes, workflows, hooks, events, and services;
@@ -89,6 +91,7 @@ Read [Architecture](docs/architecture.md) for the ownership and failure boundari
 | Providers | Native Anthropic, Amazon Bedrock, Google Gemini/Vertex, Mistral, OpenAI Responses/Azure, OpenAI-compatible, remote gateway, and message-gateway transports; retry/fallback decorators |
 | Generated media | Provider-neutral image/audio/video registry, generic async HTTP jobs, and a dedicated OpenRouter image adapter with progressive previews |
 | Persistence | Crash-tolerant local snapshots plus optional append-only session history, cross-process coordination, action journals, workflow checkpoints, memories, mailboxes, artifacts, delegations, skills, and prompt templates |
+| Semantic memory | Optional model-agnostic embeddings, authoritative-save verification, rebuildable local vector index, hybrid lexical/vector recall, structured diagnostics, and game-time reranking |
 | Placement | Shared `netstandard2.1` runtime in Godot, Unity, or another C# host; optional .NET 8 HTTP/SSE service and engine client |
 | Engines | Godot 4.7 .NET and Unity 6 packages, both exercised in real Windows editors |
 

README.zh-CN.md

@@ -12,7 +12,7 @@ OpenGameAgent 把小型、可组合的 Agent 内核带进游戏开发。它的
 
 输入是有大小限制的 JSON，可以表示对话、战斗观察、模拟 Tick、UI 事件、计划、传感状态或任意游戏数据，不要求是自然语言。项目不捆绑模型，同时支持云端和本地 API。
 
-> 当前版本：`0.3.0-alpha.1`。在 `1.0` 前公开 API 仍可能调整。
+> 当前版本：`0.3.0-alpha.2`。在 `1.0` 前公开 API 仍可能调整。
 
 内核边界刻意保持小而稳定。后续游戏特有能力通常应通过扩展、工具、策略、工作流或游戏自有服务加入，而不是继续膨胀模型/工具循环。
 
@@ -21,7 +21,8 @@ OpenGameAgent 把小型、可组合的 Agent 内核带进游戏开发。它的
 从 NuGet 安装完整的游戏 Runtime：
 
 ```bash
-dotnet add package OpenGameAgent --version 0.3.0-alpha.1
+dotnet add package OpenGameAgent --version 0.3.0-alpha.2
+dotnet add package OpenGameAgent.Memory --version 0.3.0-alpha.2 # 可选语义记忆
 ```
 
 内核、持久化、模型提供方和引擎兼容客户端也分别提供 `OpenGameAgent.*` 包。Godot、Unity 与可移植服务端压缩包可以从 [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) 页面下载。接入游戏前请阅读[快速开始](docs/getting-started.md)和[引擎接入](docs/engine-integration.md)。
@@ -38,6 +39,7 @@ OpenGameAgent 不替游戏规定玩法，而是提供可复用的游戏坐标与
 - 同一角色串行、不同角色有界并行；
 - 先记日志的动作意图与游戏权威回执；
 - 按游戏时间过滤、过期并可自定义排序的记忆；
+- 可选本地/远程嵌入、可重建向量索引与词法/向量混合召回；
 - 根据输入类型和可用工具选择的 Skills；
 - 游戏时间触发器与持久邮箱；
 - 可扩展工具、Skills、路由、Workflow、Hooks、事件与服务的类型化接口；
@@ -87,6 +89,7 @@ GameAgentRuntime
 | 提供方 | Anthropic、Amazon Bedrock、Google Gemini/Vertex、Mistral、OpenAI Responses/Azure、OpenAI-compatible、远程网关和消息网关；重试与回退包装器 |
 | 生成式媒体 | 图片/语音/视频中立注册表、通用异步 HTTP 任务，以及带渐进预览的专用图片适配器 |
 | 持久化 | 崩溃安全本地快照、可选追加式会话历史、跨进程协调、动作日志、Workflow 检查点、记忆、邮箱、产物、委派、Skills 与提示词模板 |
+| 语义记忆 | 可选模型无关嵌入、权威存档核验、可重建本地向量索引、词法/向量混合召回、结构化诊断与游戏时间重排 |
 | 运行位置 | `netstandard2.1` 共享运行时可放在 Godot、Unity 或其他 C# 宿主；可选 .NET 8 HTTP/SSE 服务端与引擎客户端 |
 | 引擎 | Godot 4.7 .NET 与 Unity 6 包，均已在 Windows 真实编辑器中通过测试 |
 

docs/agent-plugins.md

@@ -32,7 +32,7 @@ Legacy HTTP+SSE is optional in Agent Plugins 1.0.0 and is not implemented. Its e
 Install the optional adapter package alongside the core runtime:
 
 ```powershell
-dotnet add package OpenGameAgent.Plugins --version 0.3.0-alpha.1
+dotnet add package OpenGameAgent.Plugins --version 0.3.0-alpha.2
 ```
 
 ```csharp

docs/architecture.md

@@ -41,6 +41,7 @@ It does not own a universal world model. Context remains opaque JSON supplied by
 ### Optional packages
 
 - `OpenGameAgent.Extensions` adds policy, searchable tools, structured player interaction, goals, memory, artifacts, external knowledge, delegation, tracing, and durable workflow graphs.
+- `OpenGameAgent.Memory` adds an optional, model-agnostic embedding contract, rebuildable vector index, lexical/vector hybrid recall, structured diagnostics, and game-time reranking. It never replaces the authoritative memory save.
 - `OpenGameAgent.Models` adds provider/model catalogs, capability-aware selection, reasoning levels, cost metadata, dynamic refresh, and replaceable authentication.
 - `OpenGameAgent.Models.BuiltIn` turns the bundled directory into an executable multi-provider model runtime; `OpenGameAgent.Models.Auth.BuiltIn` adds explicitly configured browser and device authorization flows.
 - `OpenGameAgent.ProviderTransport` centralizes bounded response observations, header guards, and retry metadata without adding HTTP concepts to the kernel.
@@ -68,7 +69,7 @@ model tool call
   -> receipt returned to model
 ```
 
-The default operation identity is derived from the stable game input ID, model turn, and tool-call source index. It therefore remains stable even when a provider changes its generated tool-call ID during a retry. A game can replace this with a semantic identity through `GameActionOperationIdFactory`. Replaying an already closed operation returns the stored receipt.
+The default versioned operation identity is derived from the session, actor, stable game input ID, action, timeline/tick, optional save generation, model turn, and tool-call source index. It therefore remains stable when the same logical call is replayed, but cannot collide across actors, sessions, actions, or save generations. A game can replace this with a semantic identity through `GameActionOperationIdFactory`. Replaying an already closed operation returns the stored receipt, while changed arguments or authority preconditions at the same identity fail closed.
 
 The journal distinguishes `Prepared`, `Dispatched`, and a final receipt. If a process can fail after dispatch but before the receipt is recorded, `RecoverAsync` asks the game to reconcile the operation. The framework reports `Uncertain` when the game cannot prove the outcome; it never converts cancellation or a timeout into permission to repeat a write.
 
@@ -97,7 +98,7 @@ Large worlds should not invoke every NPC on every frame. Let deterministic game
 
 `IGameContextProvider` supplies current authoritative context slices. Memory is intentionally separate: `IGameMemoryStore` stores and filters records, while game code decides which retrieved memories become a context slice. This avoids silently inserting stale or private memory.
 
-The included memory stores support scopes, kinds, tags, importance, owner, game-time cutoffs, and expiry. `RankedGameMemoryStore` can apply a game-selected vector, reranking, or domain-specific ranker without requiring an embedding model in the framework.
+The included memory stores support scopes, kinds, tags, importance, owner, game-time cutoffs, and expiry. `RankedGameMemoryStore` applies a game-selected ranker. The optional `OpenGameAgent.Memory` package adds model-agnostic vector indexing and hybrid recall while keeping the original store authoritative; a game supplies its local or remote embedding implementation and explicitly rebuilds after changing its model identity.
 
 Skills are bounded instruction packages selected by input type and required tools. Skills do not install or execute code. Directory-backed skills accept either a zero-configuration `SKILL.md` with scalar `name` and `description` front matter, or `skill.json` plus a separate Markdown instruction file for game-specific filtering. Manifests are rescanned for each selection and only selected instruction files are loaded, allowing safe edits without rebuilding the runtime.
 

docs/features.md

@@ -51,8 +51,8 @@ This page maps product needs to the smallest reusable OpenGameAgent primitive.
 | Run many NPCs concurrently | `GameRuntimeLimits.MaxConcurrentActors`, `MultiActorScheduler` |
 | Correct or cancel an active NPC run | `GameAgentRuntime.TrySteer`, `GameAgentRuntime.TryAbort` |
 | Persist transcripts and deduplicate inputs | `IGameSessionStore` |
-| Keep an append-only branch/lane audit history | `IGameSessionHistoryRepository`, `GameSessionHistory` |
-| Fork, search, page, or project a session history | `GameSessionHistory`, `GameHistoryContextProjection` |
+| Build a standalone append-only branch/lane audit history | `IGameSessionHistoryRepository`, `GameSessionHistory` |
+| Fork, search, page, or project that explicit history | `GameSessionHistory`, `GameHistoryContextProjection` |
 | Compact a long transcript | `IGameTranscriptCompactor` |
 
 ## World actions and simulation
@@ -64,6 +64,8 @@ This page maps product needs to the smallest reusable OpenGameAgent primitive.
 | Execute on engine main thread | implement `IGameActionHandler` by queueing into the engine, then await the receipt |
 | Store long-term NPC facts/events | `IGameMemoryStore`, `GameMemory` |
 | Apply custom semantic ranking | `IGameMemoryRanker`, `RankedGameMemoryStore` |
+| Add local or remote vector embeddings and hybrid recall | `IMemoryEmbeddingProvider`, `VectorMemoryStore` |
+| Inspect or explicitly rebuild vectors after a model change | `RuntimeMemoryLifecycle`, `VectorMemoryStatus` |
 | Add reusable behavior instructions | `IGameSkillSource`, `GameSkill` |
 | Load portable or game-filtered skills | `DirectoryGameSkillSource` (`SKILL.md` or `skill.json`) |
 | Load reusable prompt templates with bounded arguments | `FileGamePromptTemplateLoader`, `GamePromptTemplate` |
@@ -120,7 +122,7 @@ OpenGameAgent does not prescribe:
 - pathfinding, animation, physics, combat, inventory, quests, or construction code;
 - who can observe which data;
 - NPC activation and level-of-detail policy;
-- vector database or embedding model;
+- embedding model runtime or service (the optional memory package provides the contract and derived index);
 - model vendor, prompt catalog, or monetization;
 - visual UI, world editor, or downloadable world-package format.