opencode-semantic-memory 0.8.2__tar.gz → 0.8.4__tar.gz

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-06-03
+
+### Added
+
+- **`get_by_id` tool** - Retrieve a single memory by its ID, returning the full record
+  (content, category, what/why/learned, project, entities, timestamps) plus a link summary.
+  Lets static procedures and directives be fetched directly instead of via search, which is
+  unreliable for exact retrieval. Closes #83.
+
+### Fixed
+
+- **Recall relevance** - Bulk-ingested GitLab entities could drown out genuinely relevant
+  procedures and directives. The keyword-overlap boost was unbounded
+  (`overlap_count * 0.1`), so a verbose issue/MR sharing many keywords could add an
+  arbitrarily large score. The boost is now capped at `0.2`, and the bulk-ingest
+  `relevance_weight` default is lowered `0.8` -> `0.6` to discount bulk results further
+  versus personal memories.
+
+## [0.8.3] - 2026-06-03
+
+### Fixed
+
+- **Concurrent subagent MCP connections** - Background tasks that spawned multiple
+  subagents at once could fail silently with `MCP error -32000: Connection closed`
+  when their `mcp-remote` clients all performed their startup handshake against the
+  shared HTTP server simultaneously. Two fixes:
+  - `scripts/memory-mcp.sh` now retries `mcp-remote` with exponential backoff
+    (up to 5 attempts) so a transient startup-time connection drop recovers instead
+    of leaving the subagent without memory access.
+  - The HTTP server's rate limiter now exempts loopback addresses (all local
+    sessions are trusted) and keys non-local clients by the `X-OpenCode-Session`
+    header, so concurrent sessions no longer share a single localhost bucket whose
+    limit a startup burst could trip.
+
 ## [0.8.0] - 2026-06-02
 
 ### Added

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-semantic-memory
-Version: 0.8.2
+Version: 0.8.4
 Summary: Persistent semantic memory system for OpenCode sessions
 Author-email: Gregory Havenga <ghavenga@gitlab.com>
 License-Expression: MIT

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opencode-semantic-memory"
-version = "0.8.2"
+version = "0.8.4"
 description = "Persistent semantic memory system for OpenCode sessions"
 readme = "README.md"
 license = "MIT"
@@ -52,6 +52,8 @@ opencode-memory = "opencode_memory.cli:main"
 opencode-memory-server = "opencode_memory.http_server:main"
 opencode-memory-daemon = "opencode_memory.daemon:main"
 opencode-memory-worker = "opencode_memory.background_worker:main"
+# New job-based worker (Sidekiq-like)
+opencode-memory-job-worker = "opencode_memory.jobs.worker:main"
 # Bulk ingestion commands
 opencode-memory-bulk-ingest = "opencode_memory.bulk_ingest.cli:main"
 opencode-memory-bulk-ingest-daemon = "opencode_memory.bulk_ingest.daemon:main"

opencode_semantic_memory-0.8.4/scripts/memory-mcp.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Wrapper script for opencode-memory MCP server
+# Connects to the HTTP server via mcp-remote
+#
+# Prerequisites:
+#   Linux: systemctl --user enable --now opencode-memory
+#   macOS: launchctl load ~/Library/LaunchAgents/com.opencode.memory.plist
+
+set -e
+
+SERVER_URL="http://localhost:9824"
+
+# Quick health check (fail fast if server not running)
+if ! curl -s --max-time 1 "$SERVER_URL/health" >/dev/null 2>&1; then
+    OS="$(uname -s)"
+    case "$OS" in
+        Linux*)
+            echo "Memory server not running. Start it with: systemctl --user start opencode-memory" >&2
+            ;;
+        Darwin*)
+            echo "Memory server not running. Start it with: launchctl load ~/Library/LaunchAgents/com.opencode.memory.plist" >&2
+            ;;
+        *)
+            echo "Memory server not running at $SERVER_URL" >&2
+            ;;
+    esac
+    exit 1
+fi
+
+# Resolve the mcp-remote command (locally installed is faster than npx)
+if [ -x "$HOME/.local/bin/mcp-remote" ]; then
+    MCP_REMOTE=("$HOME/.local/bin/mcp-remote")
+elif command -v mcp-remote >/dev/null 2>&1; then
+    MCP_REMOTE=(mcp-remote)
+else
+    MCP_REMOTE=(npx --yes mcp-remote)
+fi
+
+# Start mcp-remote with retry/backoff to absorb transient "Connection closed"
+# failures that occur when many subagents start concurrently (thundering herd
+# against the shared HTTP server). A clean long-running proxy never returns 0
+# here, so a fast non-zero exit means a startup-time connection drop worth retrying.
+MAX_ATTEMPTS=5
+attempt=1
+while true; do
+    start_ts=$(date +%s)
+    # Disable errexit around the proxy call; we handle its exit code explicitly.
+    set +e
+    "${MCP_REMOTE[@]}" "$SERVER_URL/mcp"
+    exit_code=$?
+    set -e
+    elapsed=$(( $(date +%s) - start_ts ))
+
+    # Exited cleanly, or ran long enough to be a real session (not a startup
+    # collision): propagate the exit code and stop.
+    if [ "$exit_code" -eq 0 ] || [ "$elapsed" -ge 10 ] || [ "$attempt" -ge "$MAX_ATTEMPTS" ]; then
+        exit "$exit_code"
+    fi
+
+    # Transient startup failure: back off (2s, 4s, 6s, 8s) and retry.
+    backoff=$(( attempt * 2 ))
+    echo "memory-mcp: mcp-remote exited ($exit_code) after ${elapsed}s on attempt ${attempt}; retrying in ${backoff}s" >&2
+    sleep "$backoff"
+    attempt=$(( attempt + 1 ))
+done

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/src/opencode_memory/background_worker.py

@@ -1,5 +1,17 @@
 """Unified background worker for all memory processing.
 
+DEPRECATED: This module is superseded by the new job-based system in
+opencode_memory.jobs.worker. The new system provides:
+- Proper job queue with claim/timeout/retry
+- Circuit breaker protection for external APIs
+- Dead job tracking and alerting
+- Metrics collection for all job types
+
+Use instead: python -m opencode_memory.jobs.worker
+
+This file is kept for backwards compatibility and will be removed in v0.10.0.
+
+Legacy documentation:
 This runs as a separate process from the MCP server, handling:
 - Embedding computation and vector storage
 - Semantic deduplication
@@ -8,8 +20,6 @@ This runs as a separate process from the MCP server, handling:
 - Memory cleanup
 - LLM-based knowledge extraction
 - Concept extraction
-
-Run with: python -m opencode_memory.background_worker
 """
 
 import asyncio
@@ -979,6 +989,20 @@ Your response (one line only):"""
 
 def main():
     """Entry point for the background worker."""
+    import warnings
+
+    warnings.warn(
+        "background_worker is deprecated and will be removed in v0.10.0. "
+        "Use 'python -m opencode_memory.jobs.worker' or the 'opencode-memory-job-worker' "
+        "command instead. The new system provides job queuing, retries, and metrics.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    logger.warning(
+        "DEPRECATION: background_worker is deprecated. "
+        "Use 'opencode-memory-job-worker' instead for the new job-based system."
+    )
+
     worker = BackgroundWorker()
 
     def handle_signal(signum, frame):

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/src/opencode_memory/bulk_ingest/config.py

@@ -47,7 +47,10 @@ class QueryConfig(BaseModel):
     """Query integration configuration."""
 
     enabled: bool = True  # Include in memory_recall searches
-    relevance_weight: float = 0.8  # Discount vs personal memories
+    # Discount bulk-ingested GitLab entities vs personal memories. Kept well
+    # below 1.0 so that procedures, directives, and decisions are not drowned
+    # out by weakly-matching bulk issues/MRs in recall results.
+    relevance_weight: float = 0.6
 
 
 class BulkIngestConfig(BaseModel):

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/src/opencode_memory/bulk_ingest/keywords.py

@@ -274,6 +274,14 @@ def compute_keyword_overlap(keywords1: list[str], keywords2: list[str]) -> int:
     return len(set(keywords1) & set(keywords2))
 
 
+# Maximum additive keyword-overlap boost. Without a cap the boost is
+# unbounded (overlap_count * boost_factor), so a verbose bulk-ingested GitLab
+# entity sharing many keywords with the query could outscore a genuinely
+# relevant personal procedure/directive. Cap it so the boost only nudges
+# ranking rather than dominating it.
+MAX_KEYWORD_BOOST = 0.2
+
+
 def keyword_boost(query_keywords: list[str], entity_keywords: list[str], boost_factor: float = 0.1) -> float:
     """Calculate keyword overlap boost for search scoring.
 
@@ -283,7 +291,7 @@ def keyword_boost(query_keywords: list[str], entity_keywords: list[str], boost_f
         boost_factor: Multiplier per overlapping keyword
 
     Returns:
-        Boost value to add to search score
+        Boost value to add to search score, capped at MAX_KEYWORD_BOOST.
     """
     overlap = compute_keyword_overlap(query_keywords, entity_keywords)
-    return overlap * boost_factor
+    return min(overlap * boost_factor, MAX_KEYWORD_BOOST)

{opencode_semantic_memory-0.8.2 → opencode_semantic_memory-0.8.4}/src/opencode_memory/http_server.py

@@ -60,6 +60,10 @@ DEFAULT_PORT = int(os.environ.get("OPENCODE_MEMORY_PORT", "9824"))
 API_KEY = os.environ.get("OPENCODE_MEMORY_API_KEY")  # Optional auth
 RATE_LIMIT = int(os.environ.get("OPENCODE_MEMORY_RATE_LIMIT", "60"))  # per minute
 
+# Loopback addresses are exempt from rate limiting: all local opencode sessions
+# and their subagents connect over loopback and are trusted.
+_LOCAL_IPS = frozenset({"127.0.0.1", "::1", "localhost"})
+
 
 class RateLimiter:
     """Simple in-memory rate limiter using sliding window."""
@@ -69,20 +73,38 @@ class RateLimiter:
         self.window_seconds = 60
         self._requests: dict[str, list[float]] = defaultdict(list)
 
-    def _get_client_id(self, scope: dict) -> str:
-        """Get client identifier from request."""
-        # Use X-Forwarded-For if behind proxy, otherwise use client IP
+    def _get_client_ip(self, scope: dict) -> str:
+        """Get the originating IP for a request."""
         headers = dict(scope.get("headers", []))
         forwarded = headers.get(b"x-forwarded-for", b"").decode()
         if forwarded:
-            client_ip = forwarded.split(",")[0].strip()
-        else:
-            client = scope.get("client", ("unknown", 0))
-            client_ip = client[0] if client else "unknown"
-        return client_ip
+            return forwarded.split(",")[0].strip()
+        client = scope.get("client", ("unknown", 0))
+        return client[0] if client else "unknown"
+
+    def _get_client_id(self, scope: dict) -> str:
+        """Get client identifier for rate limiting.
+
+        Prefers the opencode session header so that multiple concurrent
+        sessions/subagents on the same host get independent rate-limit
+        buckets rather than all sharing a single localhost IP bucket
+        (which caused startup bursts to trip the limit and drop the
+        mcp-remote connection). Falls back to client IP.
+        """
+        headers = dict(scope.get("headers", []))
+        session_id = headers.get(b"x-opencode-session", b"").decode()
+        if session_id:
+            return f"session:{session_id[:16]}"
+        return self._get_client_ip(scope)
 
     def is_allowed(self, scope: dict) -> tuple[bool, int]:
         """Check if request is allowed. Returns (allowed, retry_after_seconds)."""
+        # Local traffic is trusted and must not be rate limited: all opencode
+        # sessions and subagents connect over loopback, and throttling them
+        # only serves to break legitimate concurrent usage.
+        if self._get_client_ip(scope) in _LOCAL_IPS:
+            return True, 0
+
         client_id = self._get_client_id(scope)
         now = time.time()
         window_start = now - self.window_seconds

opencode_semantic_memory-0.8.4/src/opencode_memory/jobs/__init__.py

@@ -0,0 +1,64 @@
+"""Background job queue system (Sidekiq-like)."""
+
+from opencode_memory.jobs.circuit_breaker import (
+    CircuitBreakerManager,
+    CircuitBreakerOpenError,
+)
+from opencode_memory.jobs.executor import (
+    JobExecutor,
+    JobExecutorBuilder,
+    ResourceLimits,
+)
+from opencode_memory.jobs.handlers import JobHandlers
+from opencode_memory.jobs.queue import (
+    DEFAULT_CONFIGS,
+    JobConfigRegistry,
+    JobQueue,
+)
+from opencode_memory.jobs.scheduler import (
+    DEFAULT_SCHEDULES,
+    JobScheduler,
+    ScheduleConfig,
+)
+from opencode_memory.jobs.worker import BackgroundJobWorker
+from opencode_memory.models import (
+    BackgroundJob,
+    CircuitBreaker,
+    CircuitBreakerState,
+    DeadJob,
+    JobConfig,
+    JobMetrics,
+    JobStatus,
+    ResourceType,
+)
+
+__all__ = [
+    # Queue
+    "JobQueue",
+    "JobConfigRegistry",
+    "DEFAULT_CONFIGS",
+    # Scheduler
+    "JobScheduler",
+    "ScheduleConfig",
+    "DEFAULT_SCHEDULES",
+    # Executor
+    "JobExecutor",
+    "JobExecutorBuilder",
+    "ResourceLimits",
+    # Handlers
+    "JobHandlers",
+    # Worker
+    "BackgroundJobWorker",
+    # Circuit Breaker
+    "CircuitBreakerManager",
+    "CircuitBreakerOpenError",
+    # Models
+    "BackgroundJob",
+    "CircuitBreaker",
+    "CircuitBreakerState",
+    "DeadJob",
+    "JobConfig",
+    "JobMetrics",
+    "JobStatus",
+    "ResourceType",
+]