Fix setup.sh errors for Claude Code registration

.env.example

@@ -5,15 +5,19 @@
 QDRANT_HOST=localhost
 QDRANT_PORT=6333
 OPENEXP_COLLECTION=openexp_memories
+# Qdrant API key (RECOMMENDED — without this, any local process can read your memories)
+# If set, setup.sh will also pass it to the Docker container as QDRANT__SERVICE__API_KEY
+# Generate one with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+# QDRANT_API_KEY=
 
 # Data directory (default: ~/.openexp/data)
 # OPENEXP_DATA_DIR=~/.openexp/data
 
 # Observations directory (where Claude Code hooks write observations)
-# OPENEXP_OBSERVATIONS_DIR=~/.claude-memory/observations
+# OPENEXP_OBSERVATIONS_DIR=~/.openexp/observations
 
 # Sessions directory (where Claude Code writes session summaries)
-# OPENEXP_SESSIONS_DIR=~/.claude-memory/sessions
+# OPENEXP_SESSIONS_DIR=~/.openexp/sessions
 
 # Anthropic API key (optional — only needed for LLM-based enrichment)
 # Without this, memories are stored with basic metadata (still works great!)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug in OpenExp
+title: "[Bug] "
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages or logs if available.
+
+## Environment
+
+- OS: [e.g., macOS 14, Ubuntu 22.04]
+- Python version: [e.g., 3.11.5]
+- OpenExp version/commit: [e.g., commit hash or tag]
+- Qdrant version: [e.g., latest]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+How you'd like it to work.
+
+## Alternatives Considered
+
+Any other approaches you've thought about.
+
+## Additional Context
+
+Anything else that helps explain the request.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+Brief description of changes.
+
+## Changes
+
+- ...
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] No personal data in code (`grep -rn "sk-ant\|api_key.*=.*sk" $(git ls-files)`)
+- [ ] No hardcoded paths
+- [ ] Documentation updated (if applicable)

.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    services:
+      qdrant:
+        image: qdrant/qdrant:latest
+        ports:
+          - 6333:6333
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e .
+          pip install pytest
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

.gitignore

@@ -35,3 +35,7 @@ Thumbs.db
 
 # Qdrant data
 qdrant_storage/
+
+# Generated HTML
+*.html
+!openexp/static/*.html

CLAUDE.md

@@ -0,0 +1,79 @@
+# OpenExp — Development Instructions
+
+## Memory Protocol (MANDATORY)
+
+OpenExp gives Claude Code persistent memory with Q-learning. For it to work, follow this protocol **every task**:
+
+### Before starting any task:
+```
+search_memory("relevant context for this task")
+```
+Find prior experience, decisions, mistakes. Hooks do auto-recall on each message, but you MUST do a targeted search before complex tasks.
+
+### After completing a task:
+```
+add_memory("what was decided/done and why", type="decision")
+```
+Capture outcomes, not just actions. Q-learning needs explicit signals.
+
+### When the user shares context:
+```
+add_memory("the context", type="fact")
+```
+Immediately. Don't wait. Every piece of context improves future retrieval.
+
+### Prediction loop (build judgment over time):
+When you make a prediction or recommendation (deal outcome, approach success, client reaction):
+```
+log_prediction("prediction text", confidence=0.7, memory_ids=["ids-that-informed-this"])
+```
+Later, when the outcome is known:
+```
+log_outcome(prediction_id="pred_xxx", outcome="what happened", reward=0.8)
+```
+This is how Q-learning builds real judgment — not from heuristics, but from verified outcomes.
+Use for: deal predictions, strategy recommendations, client behavior forecasts, technical approach bets.
+
+## Architecture
+
+**Full reference:** `docs/storage-system.md` for Q-learning details, `docs/experience-library.md` for the Experience Library pipeline.
+
+- `openexp/core/` — Q-learning engine, hybrid search, scoring, lifecycle
+- `openexp/ingest/` — Transcript ingest + Experience Library pipeline (chunking, topic mapping, experience extraction)
+- `openexp/mcp_server.py` — MCP STDIO server (5 tools: search_memory, add_memory, log_prediction, log_outcome, memory_stats)
+- `openexp/cli.py` — CLI (search, ingest, chunk, topics, stats, compact, experience, viz)
+- `scripts/batch_label.py` — Batch experience labeling across all threads
+- `tests/` — 300 tests across 13 files
+
+## Q-Learning (do not change without discussion)
+
+- Formula: `Q = clamp(Q + α*reward, floor, ceiling)`
+- q_init=0.0, alpha=0.25, floor=-0.5, ceiling=1.0
+- Three layers: action (50%), hypothesis (20%), fit (30%)
+- Scoring: vector 30%, BM25 10%, recency 15%, importance 15%, Q-value 30%
+
+## Development Workflow
+
+Two remotes: `origin` (private), `public` (open-source).
+
+```bash
+# Branch from main
+git checkout -b feat/my-feature
+
+# Test
+.venv/bin/python3 -m pytest tests/ -v
+
+# Verify no private data
+grep -rn "sk-ant\|welababeldata\|ivanpasichnyk" $(git ls-files)
+
+# Push to private first, public when ready
+git push origin feat/my-feature    # daily work
+git push public main               # releases
+```
+
+## Rules
+
+- No hardcoded paths. Everything via env vars.
+- No personal data in code (API keys, usernames, company names).
+- `.env` is gitignored — never commit it.
+- Always branch → PR → squash merge. Never push to main directly.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to OpenExp
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+# Clone and set up
+git clone https://github.com/anthroos/openexp.git
+cd openexp
+./setup.sh
+
+# Activate the venv
+source .venv/bin/activate
+```
+
+Prerequisites: Python 3.11+, Docker (for Qdrant), jq.
+
+## Workflow
+
+1. **Branch from main:** `git checkout -b feat/your-feature`
+2. **Make changes**
+3. **Run tests:** `pytest tests/ -v`
+4. **Check for personal data:** `grep -rn "sk-ant\|api_key.*=.*['\"]sk" $(git ls-files)`
+5. **Push and open a PR**
+6. **Squash merge** after review
+
+## Running Tests
+
+```bash
+# All tests
+.venv/bin/python3 -m pytest tests/ -v
+
+# Specific test file
+.venv/bin/python3 -m pytest tests/test_q_value.py -v
+```
+
+## Code Guidelines
+
+- No hardcoded paths — use environment variables or relative paths
+- No personal data in code (API keys, usernames, company names)
+- `.env` is gitignored — never commit it
+- Keep dependencies minimal — avoid adding new packages without discussion
+
+## Areas Where Help Is Welcome
+
+- **Reward signals** — beyond commits/PRs, what indicates a productive session?
+- **Compaction** — merging duplicate or outdated memories automatically
+- **Multi-project learning** — sharing relevant context across projects
+- **Benchmarks** — measuring retrieval quality improvement over time
+- **More lifecycle transitions** — automated contradiction detection
+
+## Questions?
+
+Open an issue or start a discussion. We're happy to help you get oriented.