@mathew-cf/opencode-memory 1.1.0 → 1.2.0

package/dist/lib/paths.d.ts

@@ -41,6 +41,13 @@ export declare function normPath(p: string): string;
  * `path.posix.join` so the result keeps the plugin's forward-slash invariant.
  */
 export declare function normalizeDirPath(p: string): string;
+/**
+ * Resolve a caller-provided relative path beneath a trusted root.
+ *
+ * This is a lexical containment check; callers that read existing files
+ * should additionally compare their real paths if symlinks are in scope.
+ */
+export declare function resolveContainedPath(root: string, relativePath: string): string;
 /**
  * Expand a leading `~` in user-provided paths. Shells usually expand
  * this before setting OPENCODE_MEMORY_DIR, but JSON-based host configs

package/dist/lib/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CASxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAczG;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CASxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAiB/E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAczG;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/lib/rag.d.ts

@@ -53,6 +53,22 @@ export declare function installGuidance(): string;
  * parse error upstream) resolves to the empty string — degrading
  * gracefully rather than propagating shell exceptions.
  */
+export interface RagCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type RagCommandRunner = (argv: string[]) => Promise<RagCommandResult>;
+/**
+ * Execute a semantic search with source diversification. Exported with an
+ * injectable runner so compatibility behavior can be tested without spawning
+ * the installed binary.
+ */
+export declare function runRagSearch(shim: string, args: {
+    query: string;
+    indexDir: string;
+    topK?: number;
+}, runner?: RagCommandRunner): Promise<string>;
 export declare function ragSearch(args: {
     query: string;
     indexDir: string;

package/dist/lib/rag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rag.d.ts","sourceRoot":"","sources":["../../src/lib/rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAMhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,SAAS,CAEpC;AAED,uCAAuC;AACvC,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAoBxC;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAQV;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAUrD"}
+{"version":3,"file":"rag.d.ts","sourceRoot":"","sources":["../../src/lib/rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAMhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,SAAS,CAEpC;AAED,uCAAuC;AACvC,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAoBxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAmB7E;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACxD,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAQV;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAUrD"}

package/dist/lib/search-terms.d.ts

@@ -10,6 +10,7 @@
  * - Quoted phrases become a single term (with the quotes stripped).
  * - Whitespace-separated words become individual terms.
  * - Very short words (<2 chars) and common stop words are filtered out.
+ * - Duplicate terms are removed case-insensitively, preserving first-seen order.
  *
  * The original casing is preserved in the return value; downstream callers
  * lowercase when they need to compare. That's intentional: a future ranker

package/dist/lib/search-terms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-terms.d.ts","sourceRoot":"","sources":["../../src/lib/search-terms.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAcxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAItE;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgDzD"}
+{"version":3,"file":"search-terms.d.ts","sourceRoot":"","sources":["../../src/lib/search-terms.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAItE;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgDzD"}

package/dist/tools/memory.d.ts

@@ -36,14 +36,25 @@ export declare const search: ToolDefinition;
  * wrapper so tests can call it with plain arguments and assert against the
  * returned string without constructing a full tool context.
  */
+export type MemorySearchDetail = "compact" | "normal" | "debug";
 export declare function runSearch(input: {
     query: string;
     category?: string;
+    detail?: MemorySearchDetail;
 }): Promise<string>;
 export declare const list: ToolDefinition;
 export declare function runList(input: {
     category?: string;
 }): Promise<string>;
+/** Select an ATX heading and its descendants, stopping at the next peer/parent. */
+export declare function selectHeadingSection(body: string, heading: string): string | undefined;
+export declare const read: ToolDefinition;
+export declare function runRead(input: {
+    path: string;
+    heading?: string;
+    offset?: number;
+    maxChars?: number;
+}): Promise<string>;
 export declare const access: ToolDefinition;
 export declare function runAccess(input: {
     path: string;

package/dist/tools/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAiBhE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMrD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAWpG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AAkBD,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBlE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAgChE;AAID,eAAO,MAAM,MAAM,EAAE,cAYnB,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+M5F;AAED,eAAO,MAAM,IAAI,EAAE,cAWjB,CAAC;AAEH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkE3E;AAED,eAAO,MAAM,MAAM,EAAE,cAYnB,CAAC;AAEH,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBxE;AAED,eAAO,MAAM,IAAI,EAAE,cAMjB,CAAC;AAEH,wBAAsB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CA6B/C;AAED,eAAO,MAAM,KAAK,EAAE,cASlB,CAAC;AAEH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAwBhD"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA+ChE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMrD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAWpG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AAkBD,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBlE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAgChE;AAID,eAAO,MAAM,MAAM,EAAE,cAgBnB,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,wBAAsB,SAAS,CAAC,KAAK,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAoNlB;AAED,eAAO,MAAM,IAAI,EAAE,cAWjB,CAAC;AAEH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmE3E;AA6BD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0BtF;AAaD,eAAO,MAAM,IAAI,EAAE,cAuBjB,CAAC;AAEH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDlB;AAED,eAAO,MAAM,MAAM,EAAE,cAYnB,CAAC;AAsBH,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAQxE;AAED,eAAO,MAAM,IAAI,EAAE,cAMjB,CAAC;AAEH,wBAAsB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CA6B/C;AAED,eAAO,MAAM,KAAK,EAAE,cASlB,CAAC;AAEH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAwBhD"}

package/dist/tools/session.d.ts

@@ -18,6 +18,11 @@ export declare function likeOr(col: string, patterns: string[]): string;
  * used as a ranking signal so rows matching more terms surface first.
  */
 export declare function termHits(col: string, patterns: string[]): string;
+export declare function escapeLikeTerm(term: string): string;
+/** Count distinct query terms found in either the title or any session part. */
+export declare function sessionTermHits(titleCol: string, sessionIdCol: string, partsCte: string, patterns: string[]): string;
+/** Return short context centered around the earliest case-insensitive term match. */
+export declare function centerSnippet(text: string, terms: string[], maxChars?: number): string;
 export interface SessionSearchRow {
     id: string;
     title: string | null;
@@ -34,6 +39,7 @@ export interface SessionListRow {
     created: string;
     updated: string;
 }
+export declare function normalizeSessionInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number;
 export declare const search: ToolDefinition;
 export declare function runSessionSearch(input: {
     query: string;
@@ -54,6 +60,7 @@ export declare function runSessionRead(input: {
     sessionId: string;
     limit?: number;
     offset?: number;
+    messageCharOffset?: number;
     role?: "all" | "user" | "assistant";
     currentSessionId?: string;
 }): Promise<string>;

package/dist/tools/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAKhE;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAI9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAIhE;AAID,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,eAAO,MAAM,MAAM,EAAE,cA2BnB,CAAC;AAEH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAoIlB;AAED,eAAO,MAAM,IAAI,EAAE,cAqCjB,CAAC;AAEH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDlB;AAED,eAAO,MAAM,IAAI,EAAE,cAiCjB,CAAC;AAEH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,WAAW,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CA0ElB"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAMhE;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAI9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAIhE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,CAUR;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAM,GAAG,MAAM,CAUnF;AAID,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AA0BD,eAAO,MAAM,MAAM,EAAE,cA2BnB,CAAC;AAEH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgIlB;AAED,eAAO,MAAM,IAAI,EAAE,cAqCjB,CAAC;AAEH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAsDlB;AAED,eAAO,MAAM,IAAI,EAAE,cA6CjB,CAAC;AAEH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,WAAW,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAwIlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathew-cf/opencode-memory",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Persistent cross-session memory for OpenCode — a hybrid keyword + semantic search layer over a local markdown knowledge base, plus session history tools and guardrails that nudge agents to use them.",
   "author": "mat",
   "license": "Apache-2.0",

package/skills/opencode-memory/SKILL.md

@@ -13,13 +13,14 @@ The goal isn't to save everything — it's to save what took >1 minute to figure
 
 | Tool                              | Purpose                                 |
 | --------------------------------- | --------------------------------------- |
-| `memory_search(query, category?)` | Hybrid keyword + semantic search        |
+| `memory_search(query, category?, detail?)` | Compact hybrid keyword + semantic search (up to 5 results) |
+| `memory_read(path, heading?, max_chars?)` | Read bounded content and record access automatically |
 | `memory_list(category?)`          | Browse categories or list files         |
 | `memory_save()`                   | Commit + re-index after writing/editing |
 | `memory_access(path)`             | Mark a file as read & useful (bumps ranking) |
 | `memory_setup()`                  | Check `rag` install status, print guidance |
 
-Read search results with the Read tool on `~/opencode-memory/{path}`.
+Read search results with `memory_read`; use `heading` to retrieve only a relevant section. The legacy `memory_access` remains available when a memory was read through another surface.
 
 ---
 
@@ -27,7 +28,7 @@ Read search results with the Read tool on `~/opencode-memory/{path}`.
 
 ```
 START  → memory_search("what I'm working on")
-           Read relevant files; follow Related: pointers
+           memory_read relevant files or heading sections
            Verify mutable facts via live sources (not memory)
 
 DURING → Save discoveries immediately when they happen
@@ -269,7 +270,8 @@ Fix: document the target architecture as if it's already the design. If you must
 - Be specific: `memory_search("retry jitter config")` not `memory_search("retry")`
 - Multi-term = OR with ranking: `"oauth scopes"` surfaces files with both terms first
 - Filter by category: `memory_search("api-core", category="repos")`
-- Follow `Related:` pointers in results — connected knowledge is often more useful than the direct hit
+- Use `memory_read(path, heading?)` on likely matches instead of loading whole files
+- Use `detail="debug"` only when ranking diagnostics or related-file expansion is needed
 - Set `importance: high` for frequently referenced knowledge; it affects ranking
 
 ---