opencode-semantic-memory 0.6.0__tar.gz → 0.6.1__tar.gz

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/AGENTS.md

@@ -31,7 +31,7 @@ python -m opencode_memory.cli stats
 
 ## Architecture
 
-- `server.py` - MCP server with 25+ self-documenting tools
+- `server.py` - MCP server with 45+ self-documenting tools
 - `storage/sqlite.py` - SQLite + FTS5 for text search and metadata
 - `storage/vectors.py` - LanceDB for semantic vector search
 - `query/hybrid.py` - Combines FTS and vector search

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/ARCHITECTURE.md

@@ -37,6 +37,22 @@ opencode-memory uses a **3-process architecture** to separate concerns and enabl
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
+## HTTP Endpoints
+
+The HTTP server (`http_server.py`) exposes these endpoints:
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/health` | GET | No | Health check (200 if healthy, 503 if degraded) |
+| `/stats` | GET | Yes | Detailed statistics (memories, cache, queue, links) |
+| `/metrics` | GET | No | Prometheus-format metrics |
+| `/mcp` | POST | Yes | MCP protocol endpoint (Streamable HTTP transport) |
+| `/tools/{name}` | POST | Yes | Direct tool invocation (for plugin) |
+| `/log-injection` | POST | Yes | Log context injection events |
+| `/session/register` | POST | Yes | Register session with boot context IDs |
+
+**Authentication:** When `OPENCODE_MEMORY_API_KEY` is set, authenticated endpoints require the `Authorization: Bearer <key>` header.
+
 ## Processes
 
 ### 1. HTTP/MCP Server (`opencode-memory.service`)
@@ -164,6 +180,9 @@ Primary storage with FTS5 full-text search:
 - `sessions` - Active OpenCode session tracking
 - `claimed_items` - Session-exclusive item locks
 - `enrichment_queue` - Work queue for embedding computation
+- `context_events` - Unified context tracking (boot, recall, injection events)
+
+**Context Tracking Migration:** The system previously used separate `recall_events` and `context_injections` tables. These have been unified into `context_events`. During migration, data is written to both old and new tables for compatibility. The old tables will be removed in a future version.
 
 ### LanceDB (`vectors/`)
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/BOOTSTRAP.md

@@ -2,15 +2,9 @@
 
 Essential patterns for using the memory system effectively.
 
-## Session Startup (MANDATORY)
+## Session Startup
 
-Your **FIRST** action in **EVERY** session must be:
-
-```
-memory_get_boot_context()
-```
-
-This loads:
+Boot context provides essential session information:
 - **Boot gates** - Minimal STOP triggers for critical checks
 - **Active sessions** - Parallel sessions to avoid conflicts
 - **Unresolved blockers** - Known obstacles
@@ -18,7 +12,11 @@ This loads:
 - **Stale procedures** - Need review
 - **Active plans** - In-progress work
 
-Only after boot context is loaded should you process the user's request.
+**With the proactive context plugin (recommended):** Boot context is **automatically injected** at session start. No action needed - the plugin handles everything.
+
+**Without the plugin (Claude CLI, Ollama, etc.):** You must manually call `memory_get_boot_context()` as your first action in every session.
+
+The session ID is shown in the boot context footer. Use this ID when claiming items or logging session summaries.
 
 ## Core Workflow
 
@@ -52,7 +50,7 @@ memory_remember(category="plan", what="goal X", why="to achieve Y", content="mil
 ### When Done
 
 1. **Release claimed items**: `memory_release_item(session_id, item_ref)`
-2. **Log session summary**: `memory_log_session(summary, learnings, entities)`
+2. **Log session summary**: `memory_log_session(summary, learnings, entities)` - include the session ID from boot context
 
 ## Categories
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-05-20
+
+### Fixed
+- Documentation alignment: 17 fixes across all docs for consistency with v0.6.0 features
+
+## [0.6.0] - 2026-05-19
+
+### Added
+
+- **Automatic Boot Context Injection** - The proactive context plugin now automatically
+  injects boot context at session start. No need to call `memory_get_boot_context()`
+  manually when using the plugin.
+- **Session Registration** - Plugin automatically registers sessions with the memory
+  server via `/session/register` endpoint, enabling continuation detection.
+- **Boot Context Formatter** - New `boot-context-formatter.ts` module formats boot
+  context for system prompt injection with clear sections and instructions.
+- **Overdue Reminder Display** - Due reminders now show how long they've been overdue.
+- **Directory Hierarchy Cascading** - Boot gates now cascade by directory hierarchy,
+  showing both project-specific and parent directory gates.
+- **Boot Context Re-injection After Compaction** - When OpenCode compacts a session
+  (context window overflow), the plugin automatically re-injects boot context on the
+  next message, ensuring standing instructions aren't lost.
+
+### Changed
+
+- Boot context token estimate and size warning (>2000 tokens) now included in response.
+- Plugin tracks injected memory IDs to prevent duplicate context injection.
+- Session ID shown in boot context footer for continuation tracking.
+
+### Fixed
+
+- Boot gates now properly scoped by project/directory.
+
+## [0.5.0] - 2026-05-18
+
+### Added
+
+- **Unified Context Events** - New `context_events` table replaces separate
+  `recall_events` and `context_injections` tables for unified tracking.
+- **Session Columns** - Sessions table now includes `project`, `git_branch`,
+  `boot_context_ids`, `continues_session_id` for better tracking.
+- **Git Branch Detection** - Boot context now includes current git branch.
+
+### Changed
+
+- Data migration from old tables to unified `context_events` table.
+- Dual-write to both old and new tables during transition period.
+
 ## [0.4.1] - 2026-05-17
 
 ### Fixed

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-semantic-memory
-Version: 0.6.0
+Version: 0.6.1
 Summary: Persistent semantic memory system for OpenCode sessions
 Author-email: Gregory Havenga <ghavenga@gitlab.com>
 License-Expression: MIT
@@ -56,13 +56,13 @@ opencode-memory is an MCP (Model Context Protocol) server that provides long-ter
 - **Contextual directives**: Global + project-specific instructions loaded at boot
 - **Entity tracking**: Links memories to MRs, issues, epics (!123, #456, &789)
 - **GitLab enrichment**: Fetches metadata for entities from GitLab API
-- **Memory age**: All outputs show age to identify potentially outdated information
+- **Memory age**: All outputs show age (`now`, `5m`, `2h`, `3d`, `2w`, `1mo`, `2y`) to identify potentially outdated information
 - **Proactive context injection**: Automatically injects relevant memories before each LLM call (OpenCode only, via plugin)
 - **Agent-agnostic LLM support**: Works with OpenCode, Claude CLI, GitLab Duo, Ollama, or custom commands
 
 ## Prerequisites
 
-- **Python 3.11+** (check with `python3 --version`)
+- **Python 3.11+** (verify with `python3 --version` - must show 3.11 or higher)
 - **git** (for cloning the repository)
 - **venv** module (usually included with Python, or install via `python3-venv` package)
 
@@ -100,7 +100,6 @@ This will:
   - **Linux**: systemd user service
   - **macOS**: launchd LaunchAgent
 - Configure OpenCode integration
-- Create `~/.config/opencode/AGENTS.md` with memory bootstrap
 - Optionally bootstrap core directives (requires confirmation due to LLM costs)
 
 ### From Source
@@ -355,6 +354,51 @@ path = "~/.local/share/opencode-memory"
 | `memory_export_memories(output_path?, project?, categories?, since_days?)` | Export to JSON |
 | `memory_import_memories(input_path, dry_run?, skip_duplicates?)` | Import from JSON |
 
+### Reminders
+
+| Tool | Description |
+|------|-------------|
+| `memory_set_reminder(reminder_at, content?, memory_id?, recurrence?)` | Set time-triggered reminder |
+| `memory_clear_reminder(memory_id)` | Dismiss a reminder |
+| `memory_advance_reminder(memory_id)` | Move recurring reminder to next occurrence |
+| `memory_mark_procedure_reviewed(memory_id)` | Mark procedure as still accurate |
+| `memory_set_review_interval(memory_id, interval_days)` | Set procedure review frequency |
+
+### Knowledge Graph
+
+| Tool | Description |
+|------|-------------|
+| `memory_graph_aware(entity_ref, max_depth?)` | Check what knowledge exists for an entity |
+| `memory_graph_explore(entity_ref, types?, limit?)` | Discover related entities |
+| `memory_graph_retrieve(entity_refs, include_memories?)` | Get full content for entities |
+| `memory_graph_status(project?)` | Knowledge graph statistics |
+
+### Code Indexing
+
+| Tool | Description |
+|------|-------------|
+| `memory_index_codebase(path?, incremental?)` | Index code structure (classes, functions) |
+| `memory_initialize_workspace(path?, max_depth?)` | Scan directories for git repos |
+| `memory_extract_concepts(batch_size?)` | Extract semantic concepts via LLM |
+| `memory_search_code(query, symbol_types?)` | Search indexed code symbols |
+
+### GitLab Spider
+
+| Tool | Description |
+|------|-------------|
+| `memory_spider_search(entity_ref, project?, max_depth?)` | Crawl GitLab entity into knowledge graph |
+| `memory_spider_status()` | Check spider queue status |
+| `memory_spider_query(query?, author?, entity_type?)` | Search crawled GitLab content |
+
+### Analytics
+
+| Tool | Description |
+|------|-------------|
+| `memory_effectiveness_report(days?)` | Memory usage patterns and suggestions |
+| `memory_background_report(days?)` | Background process activity |
+| `memory_tool_metrics(action?, since_hours?)` | MCP tool call timing metrics |
+| `memory_vector_index(action?)` | Manage vector search index |
+
 ### Utilities
 
 | Tool | Description |
@@ -364,6 +408,7 @@ path = "~/.local/share/opencode-memory"
 | `memory_bootstrap_memory(path?)` | Scan project files for initial facts |
 | `memory_log_session(summary, learnings?, entities?)` | Log session summary |
 | `memory_memory_status()` | Check system health and queue status |
+| `memory_get_proactive_context(query, entities?, project?)` | Get context for proactive injection (plugin use) |
 
 ## Memory Categories
 
@@ -404,6 +449,7 @@ The daemon automatically:
 | `OPENCODE_MEMORY_PORT` | HTTP server port (default: 9824) |
 | `OPENCODE_MEMORY_API_KEY` | Optional API key for authentication |
 | `OPENCODE_MEMORY_RATE_LIMIT` | Requests per minute per client (default: 60) |
+| `SKIP_BOOTSTRAP` | Set to `1` to skip directive bootstrapping prompt in setup script |
 
 ## Development
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/README.md

@@ -21,13 +21,13 @@ opencode-memory is an MCP (Model Context Protocol) server that provides long-ter
 - **Contextual directives**: Global + project-specific instructions loaded at boot
 - **Entity tracking**: Links memories to MRs, issues, epics (!123, #456, &789)
 - **GitLab enrichment**: Fetches metadata for entities from GitLab API
-- **Memory age**: All outputs show age to identify potentially outdated information
+- **Memory age**: All outputs show age (`now`, `5m`, `2h`, `3d`, `2w`, `1mo`, `2y`) to identify potentially outdated information
 - **Proactive context injection**: Automatically injects relevant memories before each LLM call (OpenCode only, via plugin)
 - **Agent-agnostic LLM support**: Works with OpenCode, Claude CLI, GitLab Duo, Ollama, or custom commands
 
 ## Prerequisites
 
-- **Python 3.11+** (check with `python3 --version`)
+- **Python 3.11+** (verify with `python3 --version` - must show 3.11 or higher)
 - **git** (for cloning the repository)
 - **venv** module (usually included with Python, or install via `python3-venv` package)
 
@@ -65,7 +65,6 @@ This will:
   - **Linux**: systemd user service
   - **macOS**: launchd LaunchAgent
 - Configure OpenCode integration
-- Create `~/.config/opencode/AGENTS.md` with memory bootstrap
 - Optionally bootstrap core directives (requires confirmation due to LLM costs)
 
 ### From Source
@@ -320,6 +319,51 @@ path = "~/.local/share/opencode-memory"
 | `memory_export_memories(output_path?, project?, categories?, since_days?)` | Export to JSON |
 | `memory_import_memories(input_path, dry_run?, skip_duplicates?)` | Import from JSON |
 
+### Reminders
+
+| Tool | Description |
+|------|-------------|
+| `memory_set_reminder(reminder_at, content?, memory_id?, recurrence?)` | Set time-triggered reminder |
+| `memory_clear_reminder(memory_id)` | Dismiss a reminder |
+| `memory_advance_reminder(memory_id)` | Move recurring reminder to next occurrence |
+| `memory_mark_procedure_reviewed(memory_id)` | Mark procedure as still accurate |
+| `memory_set_review_interval(memory_id, interval_days)` | Set procedure review frequency |
+
+### Knowledge Graph
+
+| Tool | Description |
+|------|-------------|
+| `memory_graph_aware(entity_ref, max_depth?)` | Check what knowledge exists for an entity |
+| `memory_graph_explore(entity_ref, types?, limit?)` | Discover related entities |
+| `memory_graph_retrieve(entity_refs, include_memories?)` | Get full content for entities |
+| `memory_graph_status(project?)` | Knowledge graph statistics |
+
+### Code Indexing
+
+| Tool | Description |
+|------|-------------|
+| `memory_index_codebase(path?, incremental?)` | Index code structure (classes, functions) |
+| `memory_initialize_workspace(path?, max_depth?)` | Scan directories for git repos |
+| `memory_extract_concepts(batch_size?)` | Extract semantic concepts via LLM |
+| `memory_search_code(query, symbol_types?)` | Search indexed code symbols |
+
+### GitLab Spider
+
+| Tool | Description |
+|------|-------------|
+| `memory_spider_search(entity_ref, project?, max_depth?)` | Crawl GitLab entity into knowledge graph |
+| `memory_spider_status()` | Check spider queue status |
+| `memory_spider_query(query?, author?, entity_type?)` | Search crawled GitLab content |
+
+### Analytics
+
+| Tool | Description |
+|------|-------------|
+| `memory_effectiveness_report(days?)` | Memory usage patterns and suggestions |
+| `memory_background_report(days?)` | Background process activity |
+| `memory_tool_metrics(action?, since_hours?)` | MCP tool call timing metrics |
+| `memory_vector_index(action?)` | Manage vector search index |
+
 ### Utilities
 
 | Tool | Description |
@@ -329,6 +373,7 @@ path = "~/.local/share/opencode-memory"
 | `memory_bootstrap_memory(path?)` | Scan project files for initial facts |
 | `memory_log_session(summary, learnings?, entities?)` | Log session summary |
 | `memory_memory_status()` | Check system health and queue status |
+| `memory_get_proactive_context(query, entities?, project?)` | Get context for proactive injection (plugin use) |
 
 ## Memory Categories
 
@@ -369,6 +414,7 @@ The daemon automatically:
 | `OPENCODE_MEMORY_PORT` | HTTP server port (default: 9824) |
 | `OPENCODE_MEMORY_API_KEY` | Optional API key for authentication |
 | `OPENCODE_MEMORY_RATE_LIMIT` | Requests per minute per client (default: 60) |
+| `SKIP_BOOTSTRAP` | Set to `1` to skip directive bootstrapping prompt in setup script |
 
 ## Development
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/docs/BOOTSTRAP_MEMORIES.md

@@ -117,10 +117,10 @@ These memories should be ingested to make the AI more effective at using the Ope
 ```json
 {
   "category": "procedure",
-  "content": "At session start: (1) Call memory_get_boot_context() first - before anything else, (2) Register with memory_session_start(session_id, working_on) for coordination, (3) Check memory_get_active_sessions() to avoid conflicts. During work: claim items before changing, remember important things immediately. At session end: release claimed items, optionally log session summary with memory_log_session().",
-  "what": "Session lifecycle: boot context -> register -> claim -> work -> release",
+  "content": "With the proactive context plugin: Boot context is automatically injected at session start - no action needed. Session registration happens automatically. Without the plugin (Claude CLI, Ollama): Call memory_get_boot_context() first, then register with memory_session_start(). During work: claim items before changing with memory_claim_item(), remember important things immediately. At session end: release claimed items, optionally log session summary with memory_log_session().",
+  "what": "Session lifecycle: boot context (auto or manual) -> claim -> work -> release",
   "why": "Proper session lifecycle enables coordination across parallel instances",
-  "learned": "The session system prevents conflicts and enables continuity"
+  "learned": "Plugin handles boot context automatically; manual call only needed without plugin"
 }
 ```
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/docs/GITLAB_WORKFLOW_MEMORIES.md

@@ -167,13 +167,15 @@ These memories are specific to optimizing GitLab workflows with OpenCode. They d
 
 ## How the Two-Tier System Works
 
+> **Note:** With the proactive context plugin, boot context is automatically injected at session start. The flow below happens automatically - manual `memory_get_boot_context()` calls are only needed when not using the plugin.
+
 ```
 Session Start
      │
      ▼
 ┌─────────────────────┐
-│ memory_get_boot_    │
-│ context()           │
+│ Boot context loaded │
+│ (auto or manual)    │
 └─────────────────────┘
      │
      ▼

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/plugin/README.md

@@ -52,6 +52,8 @@ Add to `~/.config/opencode/opencode.json`:
 | `OPENCODE_MEMORY_API_KEY` | (none) | Optional API key |
 | `OPENCODE_MEMORY_TIMEOUT` | `10000` | Request timeout (ms) |
 
+**Note:** Project context is auto-detected from the OpenCode session's working directory via git remote.
+
 ## Architecture
 
 ```
@@ -80,7 +82,7 @@ Add to `~/.config/opencode/opencode.json`:
 ┌─────────────────────────────────────────────────────────────┐
 │                  Memory MCP Server                           │
 │                                                              │
-│  POST /tools/get_proactive_context                           │
+│  POST http://localhost:9824/tools/get_proactive_context      │
 │  ┌──────────────────────────────────────────────────────┐   │
 │  │ • Entity-specific context lookup                      │   │
 │  │ • Semantic search on query                            │   │

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/plugin/src/boot-context-formatter.ts

@@ -72,9 +72,11 @@ export function formatBootContextForSystem(
 
   // Due reminders
   if (boot.due_reminders && boot.due_reminders.length > 0) {
-    sections.push('\n### Due Reminders\n');
+    sections.push('\n### Due Reminders');
+    sections.push('**ACTION REQUIRED:** Proactively inform the user about these due reminders at the start of the session, including how long overdue each one is.\n');
     for (const reminder of boot.due_reminders) {
-      sections.push(`- **${reminder.what || 'Reminder'}**: ${reminder.content.substring(0, 200)}`);
+      const overdue = reminder.overdue || reminder.age || 'due';
+      sections.push(`- **${reminder.what || 'Reminder'}** (${overdue}): ${reminder.content.substring(0, 200)}`);
     }
   }
 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/plugin/src/index.ts

@@ -233,6 +233,75 @@ export const server: Plugin = async (input, _options) => {
       }
     },
 
+    /**
+     * Hook: experimental.session.compacting
+     * 
+     * Called before compaction summary is generated.
+     * Inject memory-specific context to preserve in the compaction summary.
+     */
+    'experimental.session.compacting': async ({ sessionID }, output) => {
+      debugLog(`[session.compacting] sessionID=${sessionID}`);
+      
+      // Get claimed items for this session from memory service
+      let claimedItems: string[] = [];
+      try {
+        const bootContext = await client.getBootContext(defaultProject, sessionDirectory);
+        // Find this session's claims
+        const thisSession = bootContext?.active_sessions?.find(s => s.id === sessionID);
+        claimedItems = thisSession?.claimed_items ?? [];
+      } catch (err) {
+        debugLog(`[session.compacting] error fetching claims: ${err}`);
+      }
+      
+      const contextLines: string[] = [
+        '## Memory System State (Preserve in Summary)',
+        '',
+        'The following memory-related state should be preserved in the compaction summary:',
+        '',
+      ];
+      
+      if (claimedItems.length > 0) {
+        contextLines.push(`**Claimed Items:** ${claimedItems.join(', ')}`);
+        contextLines.push('- These items are locked by this session - must call memory_release_item when done');
+      }
+      
+      contextLines.push('');
+      contextLines.push('**Important:** Boot context (standing instructions, blockers, reminders) will be');
+      contextLines.push('re-injected automatically after compaction. Focus on preserving task-specific state.');
+      
+      output.context.push(contextLines.join('\n'));
+      debugLog(`[session.compacting] injected ${contextLines.length} lines of context`);
+    },
+
+    /**
+     * Event: session.compacted
+     * 
+     * Called after a session has been compacted (context window overflow).
+     * We reset boot injection tracking so that boot context is re-injected
+     * on the next message - compaction summarizes away the original boot context.
+     */
+    event: async ({ event }) => {
+      if (event.type === 'session.compacted') {
+        const sessionID = (event.properties as { sessionID?: string })?.sessionID;
+        if (sessionID) {
+          debugLog(`[session.compacted] resetting boot injection for session ${sessionID}`);
+          
+          // Reset boot injection tracking - will re-inject on next message
+          sessionBootInjected.delete(sessionID);
+          
+          // Clear context caches
+          sessionContextCache.delete(sessionID);
+          bootContextCache.delete(sessionID);
+          
+          // Clear injected memory IDs - fresh start after compaction
+          injectedMemoryIds.delete(sessionID);
+          
+          // Reset turn counter
+          sessionTurnNumbers.delete(sessionID);
+        }
+      }
+    },
+
     /**
      * Hook: experimental.chat.system.transform
      * 

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/plugin/src/memory-client.ts

@@ -333,6 +333,7 @@ export interface BootContextReminder {
   reminder_at?: string;
   recurrence?: string;
   age?: string;
+  overdue?: string;
 }
 
 export interface BootContextProcedure {
@@ -343,7 +344,7 @@ export interface BootContextProcedure {
   review_action?: string;
 }
 
-export interface BootContextSession {
+export interface BootContextRecentSession {
   title: string;
   topics?: string;
   outcome?: string;
@@ -356,7 +357,7 @@ export interface BootContextResponse {
   unresolved_blockers?: BootContextMemory[];
   recent_decisions?: BootContextMemory[];
   boot_gates?: BootContextMemory[];
-  recent_sessions?: BootContextSession[];
+  recent_sessions?: BootContextRecentSession[];
   hot_entities?: any[];
   key_procedures?: BootContextMemory[];
   active_plans?: any;

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opencode-semantic-memory"
-version = "0.6.0"
+version = "0.6.1"
 description = "Persistent semantic memory system for OpenCode sessions"
 readme = "README.md"
 license = "MIT"

{opencode_semantic_memory-0.6.0 → opencode_semantic_memory-0.6.1}/src/opencode_memory/server.py

@@ -2769,6 +2769,7 @@ class MemoryServer:
                     "reminder_at": m.reminder_at.isoformat() if m.reminder_at else None,
                     "recurrence": m.recurrence,
                     "age": _format_age(m.created_at),
+                    "overdue": _format_age(m.reminder_at) + " overdue" if m.reminder_at else None,
                 }
                 for m in due_reminders
             ]