opencode-engram 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](./README.zh.md) | [繁體中文](./README.zht.md)
 
-A pull-based conversation history retrieval plugin for [OpenCode](https://github.com/opencode-ai/opencode).
+An [OpenCode](https://github.com/opencode-ai/opencode) plugin that gives agents on-demand access to full conversation history — replacing lossy context compression with structured navigation, and bridging context gaps in multi-agent workflows.
 
 Internet information is public-tier experience, local environment information is project-tier experience, and the conversation history agents accumulate during their work — reasoning chains, rejected paths, user constraints — is task-tier experience. Yet this history, the closest to actual work, almost always sinks into storage right after it's produced, never reused by subsequent agents. Engram treats conversation history as an equally important **third information source**, letting agents pull on demand during execution — at the moment of maximum information, the role that best understands the need autonomously decides what it needs.
 

package/README.zh.md

@@ -1,6 +1,6 @@
 # opencode-engram
 
-为 [OpenCode](https://github.com/opencode-ai/opencode) 开发的拉取式（Pull-based）对话历史检索插件。
+[OpenCode](https://github.com/opencode-ai/opencode) 插件，让代理按需访问完整的对话历史——以结构化导航替代有损上下文压缩，弥合多代理工作流中的上下文缺口。
 
 互联网信息是公共级的经验，本地环境信息是项目级的经验，而代理在工作中积累的对话历史——推理链、否决路径、用户约束——是任务级的经验。然而这些最贴近实际工作的历史几乎在产生后就沉入存储，从未被后续代理重新利用。Engram 将对话历史视作拥有同等地位的**第三信息源**，让代理在执行过程中按需拉取（Pull），在信息最充分的时刻，由最了解需求的角色自主决定需要什么。
 

package/README.zht.md

@@ -1,6 +1,6 @@
 # opencode-engram
 
-為 [OpenCode](https://github.com/opencode-ai/opencode) 開發的拉取式（Pull-based）對話歷史檢索插件。
+[OpenCode](https://github.com/opencode-ai/opencode) 插件，讓代理按需存取完整的對話歷史——以結構化導航取代有損上下文壓縮，彌合多代理工作流中的上下文缺口。
 
 網際網路資訊是公共層級的經驗，本地環境資訊是專案層級的經驗，而代理在工作中累積的對話歷史——推理鏈、否決路徑、使用者約束——則是任務層級的經驗。然而這些最貼近實際工作的歷史幾乎在產生後就沉入儲存空間，從未被後續代理重新利用。Engram 將對話歷史視作同等重要的**第三資訊來源**，讓代理在執行過程中按需拉取（Pull），在資訊最充分的時刻，由最了解需求的角色自主決定需要什麼。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-engram",
-  "version": "0.1.0",
-  "description": "Pull-based history retrieval plugin for OpenCode.",
+  "version": "0.1.1",
+  "description": "OpenCode plugin that gives agents on-demand access to full conversation history, replacing lossy compression with structured navigation.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,11 +13,16 @@
   },
   "keywords": [
     "opencode",
+    "opencode-plugin",
     "plugin",
+    "agent",
+    "context",
     "history",
     "retrieval",
-    "agent",
-    "context"
+    "conversation",
+    "multi-agent",
+    "context-compression",
+    "context-window"
   ],
   "type": "module",
   "main": "./src/common/plugin.ts",

package/src/common/history-prompt.ts

@@ -1,36 +1,35 @@
 export const builtInHistoryPromptBody = `## Session History
 
-Conversation history is the only authoritative source of past state: what was
-done, why, what was decided, and what remains. Treat it as a first-class source
-alongside the local workspace.
+Conversation history is the only authoritative source of past state: what was done, why, what was decided, and what remains. Treat it as a first-class source alongside the local workspace.
 
 Retrieve from history when the consequence of NOT having the information is:
-- Wrong direction: acting on a requirement, constraint, or decision you can't
-  verify from current context
-- Wrong context: user corrections, rejections, or hard constraints that shaped
-  prior work
-- Missing substance: plans, specs, schemas, or analyses not present in current
-  context
+- Wrong direction: acting on a requirement, constraint, or decision you can't verify from current context
+- Wrong context: user corrections, rejections, or hard constraints that shaped prior work
+- Missing substance: plans, specs, schemas, or analyses not present in current context
 
 ### Efficiency
 
-- Prefer search over manual browse-window scanning when you do not already know
-  the approximate location of the answer.
+- Prefer search over manual browse-window scanning when you do not already know the approximate location of the answer.
 - Do not call pull unless the preview or search snippet is clearly insufficient.
-- Parallel independent calls — multiple searches or pulls that don't depend on
-  each other should run in the same round.
+- Parallel independent calls — multiple searches or pulls that don't depend on each other should run in the same round.
+- Browse in small window (e.g., 3) initially.
 
-### Turn Mechanics
+### Technique 
 
-- history_browse_turns returns visible turns in ascending order and can focus on
-  a window around a specific \`turn_index\`.
-- If a requested turn is hidden by self-session filtering, retry with a nearby
-  visible turn.
-- history_browse_messages returns a message window around a specific
-  \`message_id\`, with \`before_message_id\` and \`after_message_id\` for
-  extending the window.
-- Use history_pull_message for full message content.`;
+#### Browse (Turns & Messages)
+- **Recent items**: Set \`num_before\`, omit \`num_after\` and ID/index.
+- **From start (turns)**: Set \`turn_index=1\`, omit \`num_before\`.
+- **Nearby context**: Set a specific ID/index and a small window to explore around a search result.
+- **Full turn (messages)**: Set \`message_id=user.message_id\` and \`num_after=assistant.total_messages\`.
 
+#### Search (history_search)
+- **Precise**: Set \`literal=true\` for exact substring matches (e.g., unique identifiers, paths). Avoid for common terms.
+- **Minimal**: Filter by type to reduce noise:
+  - \`type=[text]\`: Find specific communications/messages.
+  - \`type=[tool]\`: Locate paths, errors, or identifiers.
+  - \`type=[reasoning]\`: Find decision rationales.
+- **Maximal**: Set \`type=[text,tool,reasoning]\` to verify the existence of a fact across all layers. Ineffective for retrieving detailed context.
+`
 // =============================================================================
 // State Management
 // =============================================================================

package/src/common/plugin.ts

@@ -123,7 +123,7 @@ function normalizeSearchLiteral(literal?: boolean): boolean {
 
 function normalizeSearchTypes(value?: string[]): SearchPartType[] {
   if (value === undefined) {
-    return ["text"];
+    return ["text", "tool"];
   }
 
   if (!Array.isArray(value) || value.length === 0) {
@@ -322,7 +322,7 @@ RETURNS: turn summaries in ascending turn_index order. Each turn includes user p
           turn_index: tool.schema
             .number()
             .optional()
-            .describe("Target turn_index. Omit to use the newest visible turn"),
+            .describe("Target turn_index (starting from 1, not 0) for returning. Omit to automatically set the newest visible turn_index"),
           num_before: tool.schema
             .number()
             .optional()
@@ -380,7 +380,7 @@ RETURNS: messages[] plus before_message_id / after_message_id anchors for extend
           message_id: tool.schema
             .string()
             .optional()
-            .describe("Anchor message_id. Omit to use the newest visible message"),
+            .describe("Anchor message_id. Omit to automatically set the newest visible message_id"),
           num_before: tool.schema
             .number()
             .optional()
@@ -555,7 +555,7 @@ RETURNS: Matching messages grouped by relevance. Each message includes role, tur
           type: tool.schema
             .array(tool.schema.string())
             .optional()
-            .describe("Searchable content types to include. One or more of text, tool, reasoning. Default [text]"),
+            .describe("Searchable content types to include. One or more of text, tool, reasoning. Default [text, tool]"),
         },
         async execute(args, ctx) {
           return runCall(