tryweb · tryweb · Mar 21, 2026 · Mar 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,27 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). Versions follow
 
 ---
 
+## [0.2.0] - 2026-03-21
+
+### Added
+
+- Cross-project memory scope with global scope support for sharing knowledge across projects.
+- Global detection heuristic with `GLOBAL_KEYWORDS` array covering distributions, containers, orchestration, shells, databases, cloud, VCS, protocols, and package managers.
+- `memory_scope_promote` tool: promote memories from project scope to global scope.
+- `memory_scope_demote` tool: demote memories from global scope back to project scope.
+- `memory_global_list` tool: list/search all global-scoped memories with optional unused filter.
+- Usage statistics tracking: `lastRecalled`, `recallCount`, and `projectCount` fields on every memory record.
+- Smart unused detection: identifies global memories not recalled within `unusedDaysThreshold` using actual recall events.
+- New config options: `globalDetectionThreshold` (default: 2), `globalDiscountFactor` (default: 0.7), `unusedDaysThreshold` (default: 30).
+
+### Changed
+
+- Dual-scope recall: `memory_search` now queries both project and global scopes with global scores discounted by 0.7x.
+- Auto-recall (system.transform) now includes global memories in context injection.
+- `memory_global_list` output now includes usage statistics (stored date, last recalled, recall count, project count).
+
+---
+
 ## [0.1.6] - 2026-03-20
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -48,6 +48,9 @@ If you already use other plugins, keep them and append `"lancedb-opencode-pro"`.
     "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
+  "globalDetectionThreshold": 2,
+  "globalDiscountFactor": 0.7,
+  "unusedDaysThreshold": 30,
   "minCaptureChars": 80,
   "maxEntriesPerScope": 3000
 }
@@ -184,6 +187,9 @@ Create `~/.config/opencode/lancedb-opencode-pro.json`:
     "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
+  "globalDetectionThreshold": 2,
+  "globalDiscountFactor": 0.7,
+  "unusedDaysThreshold": 30,
   "minCaptureChars": 80,
   "maxEntriesPerScope": 3000
 }
@@ -229,6 +235,9 @@ Supported environment variables:
 - `LANCEDB_OPENCODE_PRO_RECENCY_HALF_LIFE_HOURS`
 - `LANCEDB_OPENCODE_PRO_IMPORTANCE_WEIGHT`
 - `LANCEDB_OPENCODE_PRO_INCLUDE_GLOBAL_SCOPE`
+- `LANCEDB_OPENCODE_PRO_GLOBAL_DETECTION_THRESHOLD`
+- `LANCEDB_OPENCODE_PRO_GLOBAL_DISCOUNT_FACTOR`
+- `LANCEDB_OPENCODE_PRO_UNUSED_DAYS_THRESHOLD`
 - `LANCEDB_OPENCODE_PRO_MIN_CAPTURE_CHARS`
 - `LANCEDB_OPENCODE_PRO_MAX_ENTRIES_PER_SCOPE`
 
@@ -237,6 +246,7 @@ Supported environment variables:
 - Auto-capture of durable outcomes from completed assistant responses.
 - Hybrid retrieval (vector + lexical) for future context injection.
 - Project-scope memory isolation (`project:*` + optional `global`).
+- Cross-project memory sharing via global scope with automatic detection.
 - Memory tools:
   - `memory_search`
   - `memory_delete`
@@ -246,6 +256,9 @@ Supported environment variables:
   - `memory_feedback_wrong`
   - `memory_feedback_useful`
   - `memory_effectiveness`
+  - `memory_scope_promote`
+  - `memory_scope_demote`
+  - `memory_global_list`
   - `memory_port_plan`
 
 ## Memory Effectiveness Feedback
@@ -371,6 +384,9 @@ Example sidecar:
     "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
+  "globalDetectionThreshold": 2,
+  "globalDiscountFactor": 0.7,
+  "unusedDaysThreshold": 30,
   "minCaptureChars": 80,
   "maxEntriesPerScope": 3000
 }

diff --git a/openspec/specs/memory-dual-scope-recall/spec.md b/openspec/specs/memory-dual-scope-recall/spec.md
@@ -0,0 +1,51 @@
+# memory-dual-scope-recall Specification
+
+## Purpose
+
+When retrieving memories, automatically include both project-scoped and relevant global-scoped memories, with appropriate score weighting to prioritize project context.
+
+## Requirements
+
+### Requirement: Dual-scope parallel query
+
+The system MUST query both the active project scope and the global scope in parallel when executing `memory_search`.
+
+#### Scenario: Dual-scope search
+- **WHEN** user executes `memory_search` with query "docker alpine"
+- **THEN** the system queries memories in both `project:<current-repo>` and `global` scopes
+- **AND** results are merged into a single ranked list
+
+### Requirement: Global score discount
+
+The system MUST apply a configurable discount factor (default: 0.7) to global scope scores during merge to prevent drowning out project-specific context.
+
+#### Scenario: Score calculation
+- **WHEN** a project memory scores 0.9 and a global memory scores 0.9
+- **THEN** the project memory retains 0.9
+- **AND** the global memory is discounted to 0.63 (0.9 × 0.7)
+
+### Requirement: Scope metadata in results
+
+The system MUST include scope information in recall results so users can identify the source of each memory.
+
+#### Scenario: Result metadata
+- **WHEN** recall results are returned
+- **THEN** each result includes `metadata.scope: "project"` or `metadata.scope: "global"`
+- **AND** each result includes `metadata.source: "global"` for global memories (distinct from project source)
+
+### Requirement: Global scope inclusion toggle
+
+The system MUST respect a configuration option `includeGlobalScope` (default: `true`) to control whether global memories are included in recall.
+
+#### Scenario: Global inclusion disabled
+- **WHEN** `includeGlobalScope` is set to `false`
+- **THEN** `memory_search` only queries the project scope
+- **AND** no global memories appear in results
+
+### Requirement: Dual-scope recall for auto-recall
+
+The system MUST also apply dual-scope recall during automatic system-transform recall, not just for manual `memory_search`.
+
+#### Scenario: Auto-recall includes global
+- **WHEN** the system performs automatic context injection during system.transform
+- **THEN** global memories relevant to the query are included with appropriate discounting
diff --git a/openspec/specs/memory-global-detection/spec.md b/openspec/specs/memory-global-detection/spec.md
@@ -0,0 +1,46 @@
+# memory-global-detection Specification
+
+## Purpose
+
+Automatically detect memory content that may be applicable across projects using heuristic keyword matching, and prompt the user to confirm promotion to global scope.
+
+## Requirements
+
+### Requirement: Global keyword detection
+
+The system MUST analyze memory content against a predefined list of cross-project keywords and calculate a match score.
+
+#### Scenario: High keyword match triggers promotion prompt
+- **WHEN** memory content matches 2 or more global keywords
+- **THEN** the system presents a promotion prompt to the user
+
+#### Scenario: Low keyword match does not trigger prompt
+- **WHEN** memory content matches fewer than 2 global keywords
+- **THEN** no promotion prompt is shown and memory is stored as project-scoped
+
+### Requirement: Keyword list coverage
+
+The system MUST check for keywords from these categories:
+- Linux distributions (alpine, debian, ubuntu, centos, fedora, arch)
+- Containers (docker, dockerfile, docker-compose, containerd)
+- Orchestration (kubernetes, k8s, helm, kubectl)
+- Shells/Systems (bash, shell, linux, unix, posix, busybox)
+- Web servers (nginx, apache, caddy)
+- Databases (postgres, postgresql, mysql, redis, mongodb, sqlite)
+- Cloud platforms (aws, gcp, azure, digitalocean)
+- Version control (git, github, gitlab, bitbucket)
+- Protocols (api, rest, graphql, grpc, http, https)
+- Package managers (npm, yarn, pnpm, pip, cargo, make, cmake)
+
+### Requirement: Detection does not block storage
+
+The system MUST NOT block memory storage while awaiting promotion confirmation.
+
+#### Scenario: Memory stored while awaiting confirmation
+- **WHEN** detection triggers promotion prompt
+- **THEN** the memory is stored as project-scoped immediately
+- **AND** the promotion prompt is presented asynchronously
+
+### Requirement: Keyword detection configurable
+
+The system MUST allow configuration of the global detection threshold via `global_detection_threshold` config (default: 2).
diff --git a/openspec/specs/memory-global-list/spec.md b/openspec/specs/memory-global-list/spec.md
@@ -0,0 +1,42 @@
+# memory-global-list Specification
+
+## Purpose
+
+Provide a tool for users to view and search all global-scoped memories across projects.
+
+## Requirements
+
+### Requirement: List global memories tool
+
+The system MUST provide a `memory_global_list` tool that returns all memories with `scope: "global"`.
+
+#### Scenario: List all global memories
+- **WHEN** user invokes `memory_global_list`
+- **THEN** the system returns all global-scoped memories with their IDs, content, and timestamps
+
+#### Scenario: Search within global memories
+- **WHEN** user invokes `memory_global_list` with a search query
+- **THEN** the system returns global memories matching the query, ranked by relevance
+
+### Requirement: Global memory details
+
+The system MUST include usage statistics for each global memory.
+
+#### Scenario: Memory usage tracking
+- **WHEN** global memories are returned
+- **THEN** each entry includes:
+  - `lastRecalled`: timestamp of most recent recall
+  - `recallCount`: total number of times recalled
+  - `projectCount`: number of distinct projects that have recalled this memory
+
+### Requirement: Global memory filtering
+
+The system MUST support filtering global memories by usage status.
+
+#### Scenario: Filter unused memories
+- **WHEN** user invokes `memory_global_list` with `filter: "unused"`
+- **THEN** only memories not recalled in the past 30 days are returned
+
+#### Scenario: Filter frequently used memories
+- **WHEN** user invokes `memory_global_list` with `filter: "frequently_used"`
+- **THEN** memories with high recall counts are prioritized in results
diff --git a/openspec/specs/memory-management-commands/spec.md b/openspec/specs/memory-management-commands/spec.md
@@ -75,3 +75,41 @@ The system MUST provide a structured command for users to report whether a recal
 - **WHEN** a user submits usefulness feedback for a recalled memory result
 - **THEN** the system stores a helpfulness evaluation event that can be aggregated in recall-quality reporting
 
+### Requirement: Scope promotion tool
+
+The system MUST provide a `memory_scope_promote` tool that accepts a memory ID and confirmation flag to promote memories from project to global scope.
+
+#### Scenario: User promotes a memory
+- **WHEN** user invokes `memory_scope_promote` with a valid memory ID and `confirm: true`
+- **THEN** the memory's scope is updated to `"global"`
+- **AND** the tool returns confirmation with the updated memory details
+
+#### Scenario: Promotion without confirmation
+- **WHEN** user invokes `memory_scope_promote` without confirmation
+- **THEN** the tool returns guidance for safe execution
+
+### Requirement: Scope demotion tool
+
+The system MUST provide a `memory_scope_demote` tool that accepts a memory ID and confirmation flag to demote memories from global to project scope.
+
+#### Scenario: User demotes a memory
+- **WHEN** user invokes `memory_scope_demote` with a valid memory ID and `confirm: true`
+- **THEN** the memory's scope is updated to `"project"`
+- **AND** the tool returns confirmation with the updated memory details
+
+### Requirement: Global memory list tool
+
+The system MUST provide a `memory_global_list` tool that returns all memories with `scope: "global"` and supports optional search query and filtering.
+
+#### Scenario: List all global memories
+- **WHEN** user invokes `memory_global_list`
+- **THEN** the system returns all global-scoped memories with their IDs, content, timestamps, and usage statistics
+
+#### Scenario: Search within global memories
+- **WHEN** user invokes `memory_global_list` with a search query
+- **THEN** the system returns global memories matching the query, ranked by relevance
+
+#### Scenario: Filter unused global memories
+- **WHEN** user invokes `memory_global_list` with `filter: "unused"`
+- **THEN** only memories not recalled in the past 30 days are returned
+
diff --git a/openspec/specs/memory-scope-field/spec.md b/openspec/specs/memory-scope-field/spec.md
@@ -0,0 +1,43 @@
+# memory-scope-field Specification
+
+## Purpose
+
+Add a `scope` metadata field to memory entries to distinguish between project-specific and globally shared knowledge.
+
+## Requirements
+
+### Requirement: Memory scope field
+
+The system MUST store a `scope` field on every memory entry with value `"project"` or `"global"`, defaulting to `"project"` when not specified.
+
+#### Scenario: New memory entry inherits project scope
+- **WHEN** a new memory is stored without explicit scope
+- **THEN** the entry is stored with `scope: "project"`
+
+#### Scenario: Global memory promotion
+- **WHEN** a memory is promoted to global scope
+- **THEN** the entry's `scope` field is updated to `"global"`
+
+#### Scenario: Existing memories maintain project scope
+- **WHEN** existing memories without explicit scope are queried
+- **THEN** they are treated as `scope: "project"` for backward compatibility
+
+### Requirement: Scope field queryable
+
+The system MUST support filtering memories by scope field during storage and retrieval operations.
+
+#### Scenario: Query only project memories
+- **WHEN** retrieval is constrained to project scope
+- **THEN** memories with `scope: "global"` are excluded from results
+
+#### Scenario: Query only global memories
+- **WHEN** retrieval requests global scope only
+- **THEN** memories with `scope: "project"` are excluded from results
+
+### Requirement: Scope persisted
+
+The system MUST persist the scope field to LanceDB storage and include it in all memory entry responses.
+
+#### Scenario: Scope survives restart
+- **WHEN** the system restarts after storing a global-scoped memory
+- **THEN** the memory is still returned with `scope: "global"`
diff --git a/openspec/specs/memory-scope-promotion/spec.md b/openspec/specs/memory-scope-promotion/spec.md
@@ -0,0 +1,67 @@
+# memory-scope-promotion Specification
+
+## Purpose
+
+Provide tools for users to manually promote project-scoped memories to global scope and to demote unused global memories back to project scope.
+
+## Requirements
+
+### Requirement: Manual promotion tool
+
+The system MUST provide a `memory_scope_promote` tool that accepts a memory ID and promotes it from project to global scope.
+
+#### Scenario: User promotes a memory
+- **WHEN** user invokes `memory_scope_promote` with a valid memory ID
+- **THEN** the memory's scope is updated to `"global"`
+- **AND** the tool returns confirmation with the updated memory details
+
+#### Scenario: Promotion of non-existent memory
+- **WHEN** user invokes `memory_scope_promote` with a non-existent memory ID
+- **THEN** the tool returns an error with guidance
+
+### Requirement: Manual demotion tool
+
+The system MUST provide a `memory_scope_demote` tool that accepts a memory ID and demotes it from global to project scope.
+
+#### Scenario: User demotes a memory
+- **WHEN** user invokes `memory_scope_demote` with a valid memory ID
+- **THEN** the memory's scope is updated to `"project"`
+- **AND** the tool returns confirmation with the updated memory details
+
+#### Scenario: Demotion of project-scoped memory
+- **WHEN** user invokes `memory_scope_demote` on a project-scoped memory
+- **THEN** the tool returns an error indicating scope is already project
+
+### Requirement: Confirmation required for promotion/demotion
+
+The system MUST require explicit confirmation signal before executing scope changes.
+
+#### Scenario: Promotion without confirmation
+- **WHEN** user invokes `memory_scope_promote` without confirmation
+- **THEN** the tool returns guidance for safe execution
+
+### Requirement: Promotion prompt from detection
+
+When the global detection heuristic triggers, the system MUST present a structured prompt offering the user choices.
+
+#### Scenario: Detection prompt options
+- **WHEN** global detection triggers during memory storage
+- **THEN** the user is presented with options:
+  - "Promote to global scope" (stores the memory as global)
+  - "Keep as project scope" (keeps the memory as project-scoped)
+  - "Dismiss" (same as keep as project scope)
+
+### Requirement: Unused global detection
+
+The system MUST track when global memories are recalled and identify those not used within a configurable time window.
+
+#### Scenario: Unused global memory detected
+- **WHEN** a global memory has not been recalled in the past 30 days (configurable via `unused_days_threshold`)
+- **THEN** the system presents a demotion prompt listing unused global memories
+
+#### Scenario: Demotion prompt options for unused memories
+- **WHEN** unused global memories are detected
+- **THEN** the user is presented with options:
+  - "Demote all unused" (moves all to project scope)
+  - "Review individually" (allows per-memory demotion)
+  - "Keep all" (dismisses the prompt)