pantheon-opencode 1.0.1 → 1.0.6

package/docs/MEMORY.md

@@ -1,471 +0,0 @@
-# Pantheon Memory System Guide
-
-Pantheon's memory system provides persistent, multi-strategy memory for AI
-agents using ChromaDB (vector database) + sentence-transformers (local
-embeddings). All 14 tools are accessible via the `pantheon-memory` MCP server.
-
-**Server script:** `scripts/memory_mcp_server.py`
-**Storage:** `~/.pantheon/memory/chroma.sqlite3`
-
----
-
-## How Memory Works
-
-### Architecture
-
-```
-Agent tool call → MCP server → ChromaDB PersistentClient
-                                    │
-                            sentence-transformers
-                            (all-MiniLM-L6-v2)
-                                    │
-                            SQLite storage
-                            (~/.pantheon/memory/)
-```
-
-### Scoring Strategy
-
-Each memory retrieval uses **fusion scoring** that combines three signals:
-
-| Signal | Weight | Description |
-|--------|--------|-------------|
-| **Dense vector similarity** | Primary | ChromaDB's built-in cosine similarity between query and stored embeddings |
-| **Freshness decay** | Boost | 30-day exponential half-life. Newer entries score higher |
-| **Importance boost** | Boost | User-set `importance` (0.0–1.0). Higher = more weight |
-
-**Freshness decay formula:** `score = cosine_sim × freshness × (1 + importance)`
-
-Where `freshness = 2^(-days_since_store / 30)` — after 30 days, an entry's
-freshness contribution halves.
-
-### Memory Metadata
-
-Every entry stores:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | UUID | Auto-generated unique identifier |
-| `content` | str | The text content (max 50,000 chars) |
-| `timestamp` | ISO 8601 | When the entry was created/updated |
-| `agent` | str | Which agent stored this (e.g., `"hermes"`) |
-| `category` | str | Classification (`"memory"`, `"session_fact"`, `"decision"`, `"tool_output"`) |
-| `session_id` | str | Logical session grouping |
-| `importance` | float | 0.0–1.0 |
-| `verified` | bool | Whether claim verification ran |
-| `truncated` | bool | Whether RTK output filtering was applied |
-| `links` | list[str] \| null | Linked entry IDs (knowledge graph) |
-
----
-
-## Tool Reference
-
-### 1. `memory_store` — Store a Memory Entry
-
-Stores content with metadata. Returns entry ID and timestamp.
-
-```python
-memory_store(
-    content: str,                    # The text to store
-    category: str = "memory",        # "session_fact", "memory", "decision", "tool_output"
-    agent: str = "unknown",          # Your agent name
-    session_id: str = "default",     # Session grouping key
-    importance: float = 0.5,         # 0.0 (trivial) to 1.0 (critical)
-    truncate: bool = False,          # Apply RTK output filtering
-    links: str | list[str] | None = None  # Entry IDs to link to
-) -> str:                            # JSON: {"id": "...", "timestamp": "..."}
-```
-
-**Examples:**
-
-```python
-# Store a simple fact
-memory_store(
-    content="The JWT refresh token rotation uses SHA-256 hashing",
-    category="decision",
-    agent="hermes",
-    session_id="sprint-17",
-    importance=0.8
-)
-
-# Store with RTK filtering (dedup + truncate)
-memory_store(
-    content=large_tool_output,
-    category="tool_output",
-    truncate=True,
-    session_id="session-abc"
-)
-
-# Store with knowledge graph links
-memory_store(
-    content="User model updated with role-based access control",
-    category="decision",
-    links=["abc123", "def456"]
-)
-```
-
-### 2. `memory_search` — Search with Fusion Scoring
-
-Search by semantic similarity, with freshness and importance boosts.
-
-```python
-memory_search(
-    query: str,                      # Natural language query
-    n_results: int = 5,              # Max results (1–100)
-    category_filter: str | None = None  # Optional category filter
-) -> str:                            # JSON with ranked results
-```
-
-**Examples:**
-
-```python
-# General semantic search
-memory_search(query="how do we handle JWT refresh tokens?")
-
-# Search within a specific category
-memory_search(
-    query="database migration strategy",
-    category_filter="decision",
-    n_results=10
-)
-```
-
-### 3. `memory_recall` — Auto-Recall for Prompt Injection
-
-Takes your current context, searches memory, and returns a formatted markdown
-block ready to inject into your prompt. This is the **primary entry point** for
-agents at session start.
-
-```python
-memory_recall(
-    context: str,                    # Your current task context
-    n_results: int = 3               # Number of relevant memories (1–20)
-) -> str:                            # Formatted markdown for prompt injection
-```
-
-**Example output format:**
-
-```
-## 🔍 Relevant Past Memories
-- [2026-07-09] JWT: refresh token rotation uses SHA-256 hashing (importance: 0.8)
-  Content: The JWT refresh token rotation uses SHA-256 hashing for secure invalidation.
-...
-```
-
-**Recommended usage — call at session start:**
-
-```python
-# At the start of every session, recall relevant context
-past = memory_recall(context="implementing user authentication with JWT", n_results=5)
-# Inject `past` into your prompt for continuity
-```
-
-### 4. `memory_compress` — Compress Old Entries
-
-Summarizes the oldest entries in a session into a single compressed entry.
-This frees up search space while preserving key information.
-
-```python
-memory_compress(
-    session_id: str,                 # Session to compress
-    max_entries: int = 50,           # Max entries before compression triggers
-    compression_ratio: float = 0.5   # Target compression ratio (0.0–1.0)
-) -> str:                            # Status message
-```
-
-**When to use:** When a session has accumulated many entries (>50), call
-compress to reduce noise. The original entries remain expandable.
-
-### 5. `memory_expand` — Restore Compressed Entry
-
-If a compressed entry's detail is needed, expand it back.
-
-```python
-memory_expand(entry_id: str) -> str  # Original detailed content
-```
-
-### 6. `memory_consolidate` — Merge Similar Entries
-
-Finds entries with high cosine similarity in the same session/category and
-merges them into a single entry (keeping the most recent timestamp).
-
-```python
-memory_consolidate(
-    session_id: str | None = None    # Session scope (None = all sessions)
-) -> str:                            # Status with merge count
-```
-
-**When to use:** Periodically, to deduplicate similar memories and reduce
-vector search noise.
-
-### 7. `memory_delete` — Delete an Entry
-
-```python
-memory_delete(entry_id: str) -> str  # Status message
-```
-
-### 8. `memory_update` — Update Entry Content/Metadata
-
-```python
-memory_update(
-    entry_id: str,
-    content: str | None = None,
-    category: str | None = None,
-    importance: float | None = None
-) -> str:                            # Status message
-```
-
-### 9. `memory_link` — Create Knowledge Graph Relationship
-
-Creates a bidirectional link between two entries with a relation label.
-
-```python
-memory_link(
-    from_id: str,                    # Source entry ID
-    to_id: str,                      # Target entry ID
-    relation: str = "references"     # Relation label
-) -> str:                            # Status message
-```
-
-**Relation labels:**
-
-| Label | Meaning |
-|-------|---------|
-| `references` | General reference (default) |
-| `supersedes` | New entry replaces old one |
-| `contradicts` | Opposing information |
-| `supports` | Reinforcing evidence |
-| `causes` | Causal relationship |
-| `depends_on` | Prerequisite relationship |
-
-### 10. `memory_traverse` — Walk Knowledge Graph
-
-Starting from an entry, follow links up to `max_depth` hops.
-
-```python
-memory_traverse(
-    entry_id: str,                   # Starting entry
-    max_depth: int = 1               # Link traversal depth
-) -> str:                            # Tree of related entries with summaries
-```
-
-**Example:**
-
-```python
-# Find all related decisions linked from this entry
-graph = memory_traverse(entry_id="abc123", max_depth=2)
-```
-
-### 11. `memory_verify` — Claim Verification
-
-Verifies a memory claim exists and checks its freshness (Shokunin-style).
-
-```python
-memory_verify(entry_id: str) -> str  # JSON: {exists, fresh, age_days, ...}
-```
-
-An entry is considered **stale** if:
-- Age > 90 days (no confidence)
-- Age > 30 days and importance below 0.5
-
-### 12. `memory_sessions` — List All Sessions
-
-```python
-memory_sessions(format: str = "json") -> str  # Sessions list in JSON or markdown
-```
-
-### 13. `memory_export` — Export Memories as Markdown
-
-```python
-memory_export(
-    session_id: str | None = None,   # Filter by session
-    filename: str | None = None      # Optional file path to write to
-) -> str:                            # Markdown formatted memories
-```
-
-### 14. `memory_cleanup` — Delete Test Sessions
-
-```python
-memory_cleanup(session_prefix: str = "test-") -> str  # Status message
-```
-
-Minimum prefix length: 3 characters (safety guard).
-
----
-
-## Knowledge Graph
-
-The memory system supports a bidirectional knowledge graph via `memory_link`
-and `memory_traverse`.
-
-### Creating Links
-
-```python
-# Store entries first, then link them
-r1 = memory_store(content="Decided to use Redis for session caching", category="decision")
-r2 = memory_store(content="Implementing Redis adapter in session_service.py", category="session_fact")
-
-# Parse IDs from returned JSON
-import json
-id1 = json.loads(r1)["id"]
-id2 = json.loads(r2)["id"]
-
-# Link them
-memory_link(from_id=id1, to_id=id2, relation="causes")
-```
-
-### Traversing Links
-
-```python
-# Walk the graph
-graph = memory_traverse(entry_id=id1, max_depth=3)
-```
-
-This returns a tree structure showing all linked entries up to 3 hops away.
-
-### Link Constraints
-
-- Max depth guard prevents cycles (max 10 hops in a single traverse call)
-- Links are bidirectional — linking A→B also allows traversal B→A
-- Links stored in the entry's `links` metadata field
-
----
-
-## Freshness Decay
-
-The freshness scoring system ensures recent, important information surfaces
-above old, low-importance noise.
-
-### Decay Curve
-
-| Age | Freshness Multiplier |
-|-----|---------------------|
-| 0 days | 1.0 |
-| 30 days | 0.5 (half-life) |
-| 60 days | 0.25 |
-| 90 days | 0.125 |
-| 180 days | ~0.016 |
-
-### Practical Effects
-
-- **Recent decisions** (today–7 days) strongly prioritized
-- **Last month's work** still surfaces if important (importance ≥ 0.7)
-- **Old tool output** (session noise) naturally fades away
-- **High-importance anchors** (importance 0.9–1.0) remain relevant longer
-
-### Verification Staleness
-
-`memory_verify` flags entries as stale using:
-- **Stale**: age > 90 days (no confidence in accuracy)
-- **Warn**: age > 30 days AND importance < 0.5
-
----
-
-## Compression System
-
-The compression system (DCP-style range compression) is **deterministic** —
-not LLM-based. It groups entries by category and creates summary entries.
-
-### When to Compress
-
-```python
-# After a session accumulates many entries
-memory_compress(session_id="sprint-17", max_entries=50, compression_ratio=0.5)
-```
-
-### What Compression Does
-
-1. Finds the oldest entires in a session
-2. Groups them by category
-3. Creates a single compressed entry summarizing the group
-4. Returns a status message with the compressed entry ID
-
-### Expanding
-
-If you need details from a compressed entry:
-
-```python
-details = memory_expand(entry_id="compressed-entry-id")
-```
-
----
-
-## Agent Usage Patterns
-
-### Session Start — Always Recall
-
-Every agent should call `memory_recall` at session start:
-
-```python
-# At session start
-ctx = "implementing user authentication with refresh tokens"
-memories = memory_recall(context=ctx, n_results=5)
-# Inject into your system prompt
-```
-
-### Important Decisions — Always Store
-
-When you make a decision:
-
-```python
-memory_store(
-    content="decision details",
-    category="decision",
-    agent="hermes",
-    importance=0.9
-)
-```
-
-### Cross-Referencing — Link Related Entries
-
-When two memories are related:
-
-```python
-memory_link(from_id="decision-id", to_id="implementation-id", relation="causes")
-```
-
-### Periodic Maintenance
-
-```python
-# Consolidate duplicates
-memory_consolidate(session_id="sprint-17")
-
-# Compress old entries
-memory_compress(session_id="sprint-17", max_entries=100, compression_ratio=0.5)
-
-# Export for review
-memory_export(session_id="sprint-17", filename="/tmp/sprint-17-export.md")
-```
-
----
-
-## Storage & Performance
-
-| Aspect | Detail |
-|--------|--------|
-| **Database** | ChromaDB PersistentClient (SQLite-backed) |
-| **Location** | `~/.pantheon/memory/chroma.sqlite3` |
-| **Embedding model** | `all-MiniLM-L6-v2` (~80MB, downloaded once via sentence-transformers) |
-| **Max content length** | 50,000 characters per entry |
-| **Max results** | 100 per search, 20 per recall |
-| **Categories** | Unlimited (user-defined strings) |
-
-### Performance Tips
-
-- Use `category_filter` in `memory_search` for faster, more relevant results
-- Use `truncate=True` in `memory_store` for large tool outputs
-- Run `memory_consolidate` periodically to reduce vector search noise
-- Run `memory_compress` when a session has >50 entries
-- Use `memory_cleanup("test-")` to remove test data after development
-
----
-
-## Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-|---------|-------------|-----|
-| `memory_recall` returns empty | No entries match context | Store some content first, try broader query |
-| "Failed to store memory" | Content too long (>50k chars) | Use `truncate=True` or reduce content size |
-| Search returns irrelevant results | No entries with matching semantics | Store more content, use specific category filters |
-| Entry not found in link/traverse | ID was from a different ChromaDB instance | Check `~/.pantheon/memory/` exists and is consistent |
-| Export creates empty file | No entries match the session_id | Verify session_id with `memory_sessions()` |
-| Model download fails | No internet for first-time download | Ensure network access for `all-MiniLM-L6-v2` download |

package/docs/MIGRATION-MEMORY-BANK.md

@@ -1,139 +0,0 @@
-# Migrating Memory Bank to `.pantheon/`
-
-> **Date:** 2026-07-11
-> **Applies to:** Pantheon projects using `docs/memory-bank/` for project memory.
-
-## Why `.pantheon/`?
-
-Pantheon now standardizes all **local, generated, and ephemeral** artifacts under `.pantheon/`:
-
-```
-.pantheon/           ← Fully local (gitignored)
-├── memory-bank/     ← Project memory (ADRs, tasks, progress, context)
-├── deepwork/        ← Deepwork plans and checkpoints
-├── code-mode/       ← Orchestration scripts
-├── .tmp/            ← Ephemeral artifacts (PLAN, IMPL, REVIEW)
-└── tasks/           ← Task system
-
-docs/                ← Versioned user documentation only
-├── (installation guides, architecture, platform docs)
-```
-
-### Benefits
-
-| Before | After |
-|--------|-------|
-| Memory bank versioned in git | Memory bank local (`.gitignore`) |
-| Cluttered `docs/` with internal + user docs | Clean `docs/` with only user-facing docs |
-| No separation between generated/permanent | Clear split: `.pantheon/` = local, `docs/` = permanent |
-| `.gitignore` scattered entries | Single `.pantheon/` ignore rule |
-| Bleeding internal context into PRs | Memory stays local, only relevant code is committed |
-
-## Migration Steps
-
-### Step 1: Move memory bank
-
-```bash
-mv docs/memory-bank .pantheon/memory-bank
-```
-
-### Step 2: Update `.gitignore`
-
-Add at the end of `.gitignore`:
-
-```gitignore
-# Pantheon local data
-.pantheon/
-```
-
-Remove any old entries that are now covered:
-
-```gitignore
-# Remove these lines if they exist:
-.pantheon/deepwork/
-docs/memory-bank/.tmp/
-docs/memory-bank/.vectordb/
-```
-
-### Step 3: Remove from git tracking
-
-```bash
-git rm -r --cached docs/memory-bank/
-```
-
-This removes the files from tracking **without deleting them** (they're now at `.pantheon/memory-bank/`).
-
-### Step 4: Update scripts and references
-
-Search and replace `docs/memory-bank/` → `.pantheon/memory-bank/` across your codebase:
-
-```bash
-# Python scripts
-sed -i 's|docs/memory-bank/|.pantheon/memory-bank/|g' scripts/**/*.py
-
-# Shell scripts
-sed -i 's|docs/memory-bank/|.pantheon/memory-bank/|g' scripts/**/*.sh
-
-# Markdown docs
-sed -i 's|docs/memory-bank/|.pantheon/memory-bank/|g' docs/*.md
-```
-
-> ⚠️ Update all: agent files, instructions, skills, commands, routing, and any config that references the old path.
-
-### Step 5: (Optional) Purge from git history
-
-If you want to fully remove `docs/memory-bank/` from your git history:
-
-```bash
-# Backup first!
-git bundle create /tmp/repo-backup-$(date +%Y%m%d).bundle --all
-
-# Remove from all commits
-git filter-repo --path docs/memory-bank/ --invert-paths --force
-
-# Re-add remote and force push
-git remote add origin <your-remote-url>
-git push origin --force --all
-```
-
-> 🚨 **Warning:** This rewrites history. Coordinate with your team. All open PRs will need to be recreated.
-
-### Step 6: Commit
-
-```bash
-git add -A
-git commit -m "refactor: move memory-bank to .pantheon/ as local data"
-```
-
-## Complete `.pantheon/` Structure Reference
-
-```
-.pantheon/
-├── memory-bank/          ← Project memory (local)
-│   ├── 00-project.md
-│   ├── 01-active-context.md
-│   ├── 02-progress-log.md
-│   ├── _notes/           ← ADRs and decisions
-│   ├── _tasks/           ← Task records
-│   ├── _xref/            ← Cross-references
-│   └── .vectordb/        ← ChromaDB cache (gitignored)
-├── deepwork/             ← Deepwork plans
-├── code-mode/            ← Orchestration scripts (versioned separately in scripts/)
-├── .tmp/                 ← Ephemeral artifacts (PLAN, IMPL, REVIEW)
-├── learnings/            ← Session learnings
-└── tasks/                ← Task system
-```
-
-## FAQ
-
-### Will my memory bank be lost?
-**No.** All files are preserved — they move from `docs/memory-bank/` to `.pantheon/memory-bank/`. Nothing is deleted.
-
-### Can I still version my memory bank?
-If you prefer to keep it in git, keep `docs/memory-bank/` as-is. The `.pantheon/` convention is the recommended standard but not enforced.
-
-### Does this affect platform templates?
-**No.** Platform templates (`platform/*/`) keep `docs/memory-bank/` as reference — they are for external projects that may choose their own convention.
-
-### What about other people on my team?
-Since `.pantheon/` is gitignored, each developer gets their own local copy. The memory bank is not shared via git — use explicit handoffs for cross-team context.

package/docs/PLATFORMS.md

@@ -1,5 +0,0 @@
-# Platform Support
-
-Pantheon v1.0 is **OpenCode-only**.
-
-For installation instructions, see [INSTALLATION.md](INSTALLATION.md).

package/docs/QUICKSTART.md

@@ -1,49 +0,0 @@
-# Pantheon Quick Start
-
-## What is Pantheon
-
-A multi-agent framework for , OpenCode, , , , , and . 14 specialized agents with TDD enforcement, quality gates (Themis), and memory MCP. **v4.0** — 100/100 audit score.
-
-## Installation
-
-### Option 1: CLI (recommended, coming soon)
-```bash
-npx @pantheon/cli init
-```
-
-### Option 2: Git clone
-```bash
-git clone https://github.com/ils15/pantheon.git
-cd pantheon
-npm run sync
-```
-
-Then copy to your platform's config dir:
-```bash
-# OpenCode
-cp -r .opencode/* ~/.config/opencode/
-# Or use platform-specific scripts
-```
-
-## v4.0 What's New
-
-- **14 commands** — all `/pantheon-*` (remember, search, consolidate, forget, audit v2, cancel...)
-- **Themis 2.0** — 3-layer review (heuristic scanner + deep review + verification planning)
-- **Memory MCP** — agents read-only, Zeus auto-stores every result
-- **TUI Plugin** — live deepwork status + activity feed + toast notifications
-- **YAGNI + Anti-overengineering** — built into every agent's workflow
-- **Background Agents** — parallel execution with `subagent_depth: 2`
-
-## Usage
-
-| Command | What it does |
-|---------|-------------|
-| `/pantheon` | Council multi-agent synthesis |
-| `/pantheon-status` | System status & agent registry |
-| `/pantheon-audit --light` | Code quality scan (zero LLM) |
-| `/pantheon-deepwork` | Multi-phase task execution |
-| `/pantheon-remember` | Store in memory |
-| `/pantheon-search` | Search memory |
-| `/pantheon-cancel` | Stop auto-continuation |
-
-Full list: 14 commands — all start with `/pantheon-`.

package/docs/README.md

@@ -1,18 +0,0 @@
-# Pantheon Documentation
-
-Reference documentation for the Pantheon multi-agent framework.
-
-## Contents
-
-- **[model-routing.md](reference/model-routing.md)** — Deep analysis of model assignments per plan with per-plan fallback chains, cost optimization, and benchmark data (LMSYS Arena, SWE-bench, Artificial Analysis). Covers all 14 agents and 24 unique models.
-
-## Structure
-
-| File | Purpose |
-|------|---------|
-| `reference/` | Framework reference docs (benchmark data, model analysis, architecture) |
-| `memory-bank/` | Project-specific context — **not tracked in git** (initialized by adopters) |
-
-## Note
-
-The `docs/memory-bank/` directory is **not tracked in git**. It exists as a template structure for projects that adopt Pantheon. Each project initializes its own memory bank with project-specific context.