opencode-semantic-memory 0.1.0__py3-none-any.whl

opencode_semantic_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,531 @@
+Metadata-Version: 2.4
+Name: opencode-semantic-memory
+Version: 0.1.0
+Summary: Persistent semantic memory system for OpenCode sessions
+Author-email: Gregory Havenga <ghavenga@gitlab.com>
+License-Expression: MIT
+Keywords: ai,assistant,mcp,memory,opencode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lancedb>=0.4.0
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pylance>=0.20.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: starlette>=0.36.0
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opencode-memory
+
+Persistent semantic memory system for [OpenCode](https://opencode.ai) AI assistant sessions.
+
+## Overview
+
+opencode-memory is an MCP (Model Context Protocol) server that provides long-term memory capabilities for OpenCode sessions. It automatically learns from your workflow, stores decisions and procedures, and provides relevant context when needed.
+
+**Key benefits:**
+- Remember decisions, blockers, procedures, and facts across sessions
+- Semantic search finds relevant memories even with different wording
+- Session coordination prevents conflicts when running multiple OpenCode instances
+- Project-scoped directives for per-project instructions
+- Zero manual effort - learns passively from your workflow
+
+## Features
+
+- **Hybrid retrieval**: Combines full-text search (FTS5) with vector similarity search
+- **Instant storage**: Memories stored immediately, embeddings computed async
+- **Session coordination**: Tracks active sessions, supports item claiming to prevent conflicts
+- **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
+
+## Installation
+
+### Quick Install (Recommended)
+
+Works on both Linux and macOS:
+
+```bash
+curl -fsSL https://gitlab.com/ghavenga/opencode-memory/-/raw/master/scripts/setup.sh | bash
+```
+
+This will:
+- Clone the repository to `~/.local/share/opencode-memory-install`
+- Create a virtual environment and install dependencies
+- Download the embedding model (~90MB, one-time, runs locally)
+- Set up a background service:
+  - **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)
+
+### Cost Information
+
+**Default background processing is free** - The memory daemon uses:
+- Local embedding model (sentence-transformers, no API calls)
+- Pattern-based extraction (regex, no LLM)
+- Session summaries (stores conversations as-is, no LLM processing)
+
+**LLM-based knowledge extraction is OFF by default** - There is an optional
+feature that uses `opencode run` to analyze old conversations and extract
+procedures, decisions, and facts. This:
+- Runs every 6 hours, processing up to 50 conversations per cycle
+- Makes LLM API calls for each conversation (significant cost potential)
+- Is **disabled by default** to avoid unexpected charges
+
+To enable LLM extraction (if you want it), add to `~/.config/opencode-memory/config.toml`:
+```toml
+[ingestion]
+llm_extraction = true
+```
+
+**Optional directive bootstrapping** - The setup script can create initial
+directives using `opencode inline` (~4 LLM API calls). This prompts for
+confirmation and defaults to 'no' when running non-interactively.
+
+To skip directive bootstrapping entirely:
+```bash
+SKIP_BOOTSTRAP=1 curl -fsSL .../setup.sh | bash
+```
+
+### From Source (Manual)
+
+```bash
+# Clone the repository
+git clone https://gitlab.com/ghavenga/opencode-memory.git
+cd opencode-memory
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Download the embedding model (runs once, ~90MB)
+python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+```
+
+### From PyPI
+
+```bash
+pip install opencode-semantic-memory
+```
+
+## Quick Start
+
+### 1. Start the Memory Server
+
+The recommended setup runs a shared HTTP server that all OpenCode sessions connect to:
+
+```bash
+# Start manually
+source .venv/bin/activate
+python -m opencode_memory.http_server
+```
+
+Or install as a background service (auto-starts on login):
+
+**Linux (systemd):**
+```bash
+# Copy and customize the service file
+cp opencode-memory.service ~/.config/systemd/user/
+
+# Edit to match your paths
+nano ~/.config/systemd/user/opencode-memory.service
+
+# Enable and start
+systemctl --user daemon-reload
+systemctl --user enable --now opencode-memory
+
+# Check status
+systemctl --user status opencode-memory
+```
+
+**macOS (launchd):**
+```bash
+# Copy the plist file
+cp com.opencode.memory.plist ~/Library/LaunchAgents/
+
+# Edit to match your paths (replace $HOME with actual path)
+nano ~/Library/LaunchAgents/com.opencode.memory.plist
+
+# Create log directory
+mkdir -p ~/.local/state/opencode-memory
+
+# Load the service
+launchctl load ~/Library/LaunchAgents/com.opencode.memory.plist
+
+# Check status
+launchctl list | grep opencode
+```
+
+### 2. Configure OpenCode
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "memory": {
+      "type": "remote",
+      "url": "http://localhost:9824/mcp"
+    }
+  }
+}
+```
+
+### 3. Configure the Agent
+
+Add to `~/.config/opencode/AGENTS.md`:
+
+```markdown
+# Agent Instructions
+
+At session start, always call `memory_get_boot_context` to load prior context, active sessions, and blockers.
+
+## Memory System
+
+The memory system provides persistent context across sessions.
+
+### Proactive Usage
+
+Call `memory_remember` when:
+- You make a decision about approach
+- You hit a blocker
+- You learn how to do something
+- You discover an interesting fact
+
+Call `memory_recall(query)` before:
+- Using an unfamiliar API
+- Making assumptions about how something works
+
+Call `memory_get_context(entity_ref)` before working on any MR/issue/epic.
+
+Categories: decision, blocker, procedure, fact, event, directive
+```
+
+## Configuration
+
+Create `~/.config/opencode-memory/config.toml`:
+
+```toml
+[identity]
+user = "your-gitlab-username"  # Optional, auto-detected from git
+instance = "gitlab.com"
+
+[boot]
+identity = true
+active_sessions = true
+hot_items = true
+unresolved_blockers = true
+recent_decisions = false
+max_hot_items = 5
+
+[ingestion]
+watch_paths = ["~/.local/share/opencode/opencode.db"]
+db_poll_interval = 30
+llm_extraction = false
+working_directory = "/path/to/your/projects"
+
+[storage]
+path = "~/.local/share/opencode-memory"
+```
+
+## MCP Tools
+
+> **Note:** Tools are registered with the `memory_` prefix when accessed through the "memory" MCP server.
+> For example, `recall` becomes `memory_recall` in OpenCode sessions.
+
+### Core Memory Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_recall(query, limit?, project?, category?, compact?)` | Semantic search across memories |
+| `memory_remember(content, category, what?, why?, learned?, entities?, project?)` | Store a memory |
+| `memory_get_context(entity_ref)` | Get all memories for !MR, #issue, or &epic |
+| `memory_get_boot_context()` | Load startup context (identity, blockers, directives) |
+| `memory_get_linked_memories(memory_id, link_types?)` | Get memories linked to a specific memory |
+
+### Session Coordination
+
+| Tool | Description |
+|------|-------------|
+| `memory_session_start(session_id, working_on?)` | Register session |
+| `memory_session_end(session_id, summary?)` | End session with summary |
+| `memory_session_heartbeat(session_id)` | Keep session alive |
+| `memory_get_active_sessions()` | List active sessions |
+| `memory_claim_item(session_id, item_ref)` | Claim exclusive ownership |
+| `memory_release_item(session_id, item_ref)` | Release claimed item |
+
+### Memory Management
+
+| Tool | Description |
+|------|-------------|
+| `memory_resolve_blocker(memory_id)` | Mark blocker as resolved |
+| `memory_unresolve_blocker(memory_id)` | Reopen a blocker |
+| `memory_archive_memory(memory_id, reason?)` | Archive outdated memory (soft delete) |
+| `memory_delete_memory(memory_id, also_delete_vector?)` | Permanently delete a memory |
+| `memory_edit_memory(memory_id, content?, what?, why?, learned?)` | Edit memory content or metadata |
+| `memory_bulk_archive(memory_ids?, category?, older_than_days?, reason)` | Archive multiple memories |
+| `memory_consolidate_memory(days_stale?, project?)` | Find stale/duplicate memories |
+| `memory_search_history(query, category?, limit?)` | Search with category filter |
+
+### Backup & Transfer
+
+| Tool | Description |
+|------|-------------|
+| `memory_export_memories(output_path?, project?, categories?, since_days?)` | Export to JSON |
+| `memory_import_memories(input_path, dry_run?, skip_duplicates?)` | Import from JSON |
+
+### Utilities
+
+| Tool | Description |
+|------|-------------|
+| `memory_ingest_file(file_path)` | Manually ingest a markdown file |
+| `memory_enrich_entity(entity_ref, project?)` | Fetch GitLab metadata |
+| `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 Categories
+
+| Category | Use For |
+|----------|---------|
+| `decision` | Architectural choices, design decisions |
+| `blocker` | Obstacles preventing progress |
+| `procedure` | How-to knowledge, workflows |
+| `fact` | Project-specific information |
+| `event` | Significant occurrences |
+| `directive` | Always-on instructions (global or project-scoped) |
+| `plan` | Long-term goals and strategies |
+| `idea` | Future possibilities, deferred considerations |
+| `conversation` | Full conversation content (auto-generated) |
+
+## Storage
+
+All data is stored locally:
+
+- **SQLite**: `~/.local/share/opencode-memory/memory.db` - Memories, entities, sessions, FTS index
+- **LanceDB**: `~/.local/share/opencode-memory/vectors/` - Vector embeddings for semantic search
+
+The daemon automatically:
+- Cleans up old resolved blockers (>90 days)
+- Archives old conversations (>180 days)
+- Compacts LanceDB versions (keeps last 10)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITLAB_TOKEN` | Enable GitLab entity enrichment |
+| `HF_HUB_OFFLINE=1` | Prevent model downloads (use cached) |
+| `TRANSFORMERS_OFFLINE=1` | Prevent model downloads |
+| `OPENCODE_MEMORY_HOST` | HTTP server bind address (default: 127.0.0.1) |
+| `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) |
+
+## Development
+
+```bash
+# Activate environment
+source .venv/bin/activate
+
+# Run tests
+python -m pytest tests/ -v
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/
+
+# Check memory stats
+python -m opencode_memory.cli stats
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      opencode-memory                            │
+├─────────────────────────────────────────────────────────────────┤
+│  MCP Server (HTTP/stdio)                                        │
+│  └── 25+ tools for memory management                            │
+├─────────────────────────────────────────────────────────────────┤
+│  Background Daemon                                              │
+│  ├── OpenCode DB Observer (polls for new sessions)              │
+│  ├── Entity Enrichment (GitLab API)                             │
+│  └── Cleanup (archives old memories, compacts vectors)          │
+├─────────────────────────────────────────────────────────────────┤
+│  Storage Layer                                                  │
+│  ├── SQLite + FTS5 (memories, entities, sessions)               │
+│  └── LanceDB (vector embeddings)                                │
+├─────────────────────────────────────────────────────────────────┤
+│  Embedding Engine                                               │
+│  └── all-MiniLM-L6-v2 (384-dim, runs in subprocess)             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Operations
+
+### Log Rotation
+
+When running as a systemd service, logs are managed by journald. To configure log rotation:
+
+```bash
+# Check current log size
+journalctl --user -u opencode-memory --disk-usage
+
+# Set max journal size (add to ~/.config/systemd/user.conf or override)
+# Or create ~/.config/systemd/journald.conf.d/opencode-memory.conf:
+cat > ~/.config/systemd/journald.conf.d/opencode-memory.conf << 'EOF'
+[Journal]
+SystemMaxUse=100M
+MaxRetentionSec=7d
+EOF
+
+# Or manually vacuum old logs
+journalctl --user --vacuum-time=7d
+journalctl --user --vacuum-size=100M
+```
+
+For file-based logging, configure rotation in the systemd service:
+
+```ini
+[Service]
+StandardOutput=append:/var/log/opencode-memory/server.log
+StandardError=append:/var/log/opencode-memory/error.log
+```
+
+Then use logrotate (`/etc/logrotate.d/opencode-memory`):
+
+```
+/var/log/opencode-memory/*.log {
+    daily
+    rotate 7
+    compress
+    delaycompress
+    missingok
+    notifempty
+    create 0640 $USER $USER
+}
+```
+
+### Monitoring
+
+The HTTP server exposes several endpoints:
+
+| Endpoint | Description |
+|----------|-------------|
+| `/health` | Basic health check (returns 200 if healthy, 503 if degraded) |
+| `/stats` | Detailed statistics (memories, cache, queue, links) |
+| `/metrics` | Prometheus-format metrics |
+
+Example monitoring with curl:
+```bash
+# Health check (for load balancers/monitoring)
+curl -s http://localhost:9824/health | jq .
+
+# Full stats
+curl -s http://localhost:9824/stats | jq .
+
+# Prometheus metrics
+curl -s http://localhost:9824/metrics
+```
+
+### CLI Tools
+
+```bash
+# Show comprehensive statistics
+python -m opencode_memory.cli stats
+
+# Ingest markdown files
+python -m opencode_memory.cli ingest /path/to/notes --recursive
+
+# Archive old memories
+python -m opencode_memory.cli cleanup --dry-run
+
+# Enrich entities with GitLab metadata
+python -m opencode_memory.cli enrich --limit 100
+```
+
+## Troubleshooting
+
+### Check service status
+
+**Linux:**
+```bash
+systemctl --user status opencode-memory
+journalctl --user -u opencode-memory -f
+```
+
+**macOS:**
+```bash
+launchctl list | grep opencode
+tail -f ~/.local/state/opencode-memory/server.log
+tail -f ~/.local/state/opencode-memory/server.error.log
+```
+
+### Check memory system health
+Use `memory_status` tool or:
+```bash
+python -c "
+from opencode_memory.server import MemoryServer
+import json
+server = MemoryServer(enable_daemon=False)
+print(json.dumps(server._get_status(), indent=2))
+"
+```
+
+### Prometheus metrics
+The HTTP server exposes metrics at `/metrics`:
+```bash
+curl http://localhost:9824/metrics
+```
+
+### Backup and restore
+```bash
+# Export all memories
+memory_export_memories(output_path="/backup/memories.json")
+
+# Import on new machine
+memory_import_memories(input_path="/backup/memories.json", dry_run=True)  # Preview
+memory_import_memories(input_path="/backup/memories.json")  # Actually import
+```
+
+### Reset memory database
+
+**Linux:**
+```bash
+rm -rf ~/.local/share/opencode-memory/
+systemctl --user restart opencode-memory
+```
+
+**macOS:**
+```bash
+rm -rf ~/.local/share/opencode-memory/
+launchctl unload ~/Library/LaunchAgents/com.opencode.memory.plist
+launchctl load ~/Library/LaunchAgents/com.opencode.memory.plist
+```
+
+## License
+
+MIT

opencode_semantic_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+opencode_memory/__init__.py,sha256=1KwiQr3gV8u7XfSA-1Z-S0SaalrBs4Pnegac5UcZjiY,97
+opencode_memory/cache.py,sha256=nk8zfuTRe3p378hekp-btyVrq1-YOfI5WOZpv6vpKL8,9316
+opencode_memory/cli.py,sha256=zL_WX6BSVDLw62vk-tGcIesiAdvcXNGukoMgoLVa6g0,27168
+opencode_memory/config.py,sha256=dvgusEs3Cx-d3b_qB4jLDg61X8H63toLsZgAGbq-rsA,2785
+opencode_memory/daemon.py,sha256=RNAk05oKftgBKP-PFOSp_W7Yx2qNRtk-_xM1ezcoBYk,37367
+opencode_memory/extraction.py,sha256=tOD-nVmgGgHkbis5I8WOjYDJFEdVBqnQrqOoJYkYI-s,7562
+opencode_memory/historical_ingest.py,sha256=SRpFm9IJCFP-r_zYF4V_dAjOkJ9u2UkSXhgXi3JYMhU,4768
+opencode_memory/http_server.py,sha256=ks5A2IXnZIlrfvxL4ab_lERtPch5gJZACPgi63qDxyM,15552
+opencode_memory/metrics.py,sha256=fMGOjT_qnUfPJECX5o09RoOKbjE2fpVQUoucnV07X4E,9290
+opencode_memory/models.py,sha256=ec9ebIRei4DWyzlzRborUUak4GzpSl0Bq61KJDOT7L4,5552
+opencode_memory/project.py,sha256=1rsnfaVaWN3AsHdcD_fPYx-NzpSbqKp5eeijm_V50zc,2790
+opencode_memory/server.py,sha256=KVJfTqKbTfwDtqg6mk3DTzGfYacMubac-b6uXOxTkoU,113683
+opencode_memory/enrichment/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opencode_memory/enrichment/gitlab.py,sha256=AVTBE_BFw1ORsxNhrfkW6BoyZOsejYK2RP87AcpPTKs,8636
+opencode_memory/ingestion/__init__.py,sha256=SbNcIFHCAlfuxRiUfbiGu1Ciun7o7bfcUypFS8xaCxs,293
+opencode_memory/ingestion/embeddings.py,sha256=WeNQ5aKPTqpAO-t9iksVUFOx_6TjuB01ugeNCAE0t9E,7798
+opencode_memory/ingestion/extractors.py,sha256=9uusi2mO0hQqsyXFk-Un1GXiHNxV4DPQtMtYeR4jSyA,8868
+opencode_memory/ingestion/opencode_db.py,sha256=PPocuqjM5srvIqEqD_Xa4nrIHMYgoIvghCghwR9V1S0,16030
+opencode_memory/ingestion/parser.py,sha256=gJaWgqlG6eGTNxis3rXfwxLF0hB-xBCOxTEEqVB3cJ4,13187
+opencode_memory/ingestion/watcher.py,sha256=hVErZBWkRpBt3JDyR26M9Xg4XifjV_WZ6L42w67dyAc,3073
+opencode_memory/linking/__init__.py,sha256=gRkg9Bg6Cg2iLfMGelxjaOzBoLwO624nacnTxpTsueA,161
+opencode_memory/linking/linker.py,sha256=YPiV-RcHgRDqpounh6u__TzW1slbyrz7h9LwhocufgI,11596
+opencode_memory/query/__init__.py,sha256=1E67hgBWJReI_d7_y1AWHHJyOtbJnz06CcLWNZWVLxM,136
+opencode_memory/query/hybrid.py,sha256=P9jrceZehzZ_In9WZIOk22_W6QIoHor-BjQEm8UR2zo,7646
+opencode_memory/session/__init__.py,sha256=_VyYxFYnQMMbaRn_ZikZJahe84aVzmU_bVweLaXaCD4,147
+opencode_memory/session/registry.py,sha256=4ZN2XFD5n3QdPpMmfuJ2fFskxRs_Nt-BaIBu0filN5o,2007
+opencode_memory/storage/__init__.py,sha256=5TtB4QInB-HNjmwv2peFPJBkEQ3n3UZ144dMXdOK3Rw,205
+opencode_memory/storage/sqlite.py,sha256=C4EmPBItDBCiOLqp0bQCMXYY1TxNGx2nEcA8HGAOn7c,63433
+opencode_memory/storage/vectors.py,sha256=8pT2hNrsNtR4UWV4ROX7tizoVjoFxZEKDiM_oxYs9j4,7299
+opencode_semantic_memory-0.1.0.dist-info/METADATA,sha256=7e045gNQiXtvUtWB-2RCOeLNo3I3MQEp7ExIZSzklwc,16889
+opencode_semantic_memory-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+opencode_semantic_memory-0.1.0.dist-info/entry_points.txt,sha256=j95C-SKL5t7fy4tF8BQLY2Jy1wePUSnfbYPxyrM4TNY,119
+opencode_semantic_memory-0.1.0.dist-info/RECORD,,

opencode_semantic_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opencode_semantic_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+opencode-memory = opencode_memory.cli:main
+opencode-memory-server = opencode_memory.http_server:main