# ◆ ScreamLife — Human Decision Memory System

> **The Decision System AI Cannot Replace**
>
> A decision-memory system that records *why* you chose, not just *what* you did.

---

## ✌️ Two-Touch Product Surface

ScreamLife is built around exactly two moments:

| Touch | Tool | What happens |
|---|---|---|
| **You talk, it records** | `scream-capture` | One call classifies the utterance: an open/decided **decision** or a passed-on **missed opportunity**, and stores it automatically. No choosing between granular tools. |
| **You ask, it answers** | `scream-query` | One call dispatches every ask: advice, history, patterns, bias analysis, profile, courage report, or missed ledger (via `intent`). |
| **It talks back at the right moment** | *automatic* | After a capture, the interception engine may emit a single history-grounded nudge (SSE) — no tool call needed. Enable via `INTERCEPT_CONFIG.enabled`. |

Everything else (search, bias analysis, patterns, advice, profile, missed-ledger management) is available as granular tools for explicit control, but the default workflow is two touches.

**The lens**: not a mirror that diagnoses your biases — a ledger that also counts what staying conservative cost you.

---

## 🌟 What is ScreamLife?

**ScreamLife** is a local MCP (Model Context Protocol) service that captures your decisions during everyday AI-agent conversations, stores them as structured decision blocks, and delivers objective, personalized guidance based on your own decision history.

> Not a memory system (what you did) — a **decision system** (why you chose).

---

## 🎯 Core Value

| Value | Description |
|---|---|
| **Auto-capture** | Automatically detects decisions during agent conversations, zero manual work |
| **Structured blocks** | Context, options, choice, reasoning, confidence, outcome, reflection |
| **3-layer search** | Vector semantics + keyword + hybrid search |
| **Bias detection** | Real-time detection of 8 cognitive biases |
| **Pattern mining** | Mines behavioral patterns from your history |
| **Personalized advice** | Based on your historical patterns, not generic advice |
| **Context injection** | Auto-generates AGENTS.md so agents understand your decision style |

---

## 🧩 MCP Tools

| Tool | Function | Trigger |
|---|---|---|
| `scream-save` | Save a structured decision | Call immediately when a decision signal appears in the user message |
| `scream-create` | Manually create a decision | Precise manual entry |
| `scream-search` | 3-layer historical decision search | Check history before facing a new decision |
| `scream-get` | Fetch a single decision's details | Inspect a specific decision |
| `scream-profile` | User identity profile | Understand the user on first connection |
| `scream-bias` | Detect 8 cognitive biases | When the user expresses decision reasoning |
| `scream-patterns` | Discover behavioral patterns | When analyzing decision habits |
| `scream-advice` | Personalized decision advice | When the user faces an important decision |
| `scream-missed` | Missed-opportunities ledger: record things passed on, review expired ones, attach hindsight | The user mentions passing on an opportunity (decided not to / too risky / can't afford / turned down) |
| `scream-capture` | **Two-touch default**: auto-classify and store a decision or a missed opportunity | The user expresses a decision or a passed-on opportunity — use this instead of choosing granular tools |
| `scream-query` | **Two-touch default**: one ask tool (intent = advice/search/missed/patterns/bias/profile/courage) | The user asks for anything: advice, history, patterns, bias, profile, courage |

### scream-save Structured Fields

```
situation   What the user is considering
options     List of candidate options
choice      Final choice (empty if undecided)
reasoning   Decision reasoning
confidence  Confidence (0-1)
outcome     Outcome (pending/success/partial/failed)
reflection  Post-hoc reflection
category    Category (career/finance/health/relationship/education/tech/lifestyle/other)
user_text   [Required] The user's exact words (used to verify decision attribution)
```

> **Precision**: Only user-declared decisions are recorded. AI's own analysis/suggestions are automatically rejected.

---

## 🚀 Quick Start

### 1. Configure MCP

Add to your MCP-compatible agent's config (works with **any** MCP-compatible agent):

```json
{
  "mcpServers": {
    "scream-life": {
      "command": "bun",
      "args": ["/absolute/path/scream-life/Core/mcp-server.ts"],
      "env": {
        "SCREAM_LIFE_DB_PATH": "/absolute/path/scream-life/Data/scream-life.db"
      }
    }
  }
}
```

### 2. Optional: Hook prompts

If your agent supports hooks, configure `hooks/hooks.json` to remind the agent to check for decisions each turn.

### 3. Web Gateway

The MCP server auto-starts a web gateway at `http://localhost:3000` — view your decision timeline, inject decisions manually, and monitor in real time via SSE.

**Optional runtime switches** (set in the MCP `env`):

| Variable | Effect |
|---|---|
| `SCREAM_LIFE_WATCH=0` | Disable the transcript watcher (it is **enabled by default**). |
| `SCREAM_LIFE_WATCH_DIRS=/a,/b` | Extra comma-separated directories the watcher monitors. |
| `SCREAM_LIFE_INTERCEPT=1` | Enable automatic decision-moment nudges after captures. |
| `SCREAM_LIFE_WEB_PORT=3100` | Change the gateway port. |

**Standalone web dashboard (dev)**: the MCP gateway already serves the dashboard; to run the standalone server separately use a different port to avoid the port conflict:

```bash
PORT=3001 bun run Web/server.ts
```

### 4. Connect to an Agent Platform

The MCP server speaks the standard stdio protocol — register it as an MCP server in your agent client:

**Desktop MCP clients** — add to the client's MCP server config file (a common desktop client uses `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "scream-life": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/scream-life/Core/mcp-server.ts"],
      "env": { "SCREAM_LIFE_WATCH": "0" }
    }
  }
}
```

**Other MCP-capable clients (IDE plugins, custom agents)** — point them at the same `command`/`args`. If the client supports JSON config, use the same shape above.

**Verify it connected**: ask your agent "have I made any decisions before?" — it should call the `query` tool and answer from your history (or say there's nothing yet). Then say "I decided to try this new framework" — the agent should call `capture` to record it. If neither tool is called, check the client's MCP server list for errors.

> Note: `SCREAM_LIFE_WATCH=0` above disables the file watcher so the agent-only workflow is clean. Remove it if you also want automatic transcript capture.

---

## 🔍 3-Layer Search

| Strategy | Technology | Use case |
|---|---|---|
| `vector` | Chroma + auto-embedding | Semantic search ("startup" matches "start a company") |
| `fts5` | SQLite FTS5 | Exact keyword matching |
| `hybrid` | FTS5 filtering + vector ranking | Default, most accurate |
| `tfidf` | TF-IDF + cosine similarity | Fallback when Chroma is unavailable |

### Embedding Model

Uses the chromadb built-in multilingual model by default (`all-MiniLM-L6-v2`, zero config). An optional Chinese-optimized model `BAAI/bge-large-zh-v1.5` is supported:

```bash
# Option 1: built-in multilingual model (default, zero config)
uvx --with chromadb python3 Core/chroma_helper.py

# Option 2: BGE Chinese-optimized model (more accurate, requires model download)
SCREAM_LIFE_EMBEDDING_MODEL=BAAI/bge-large-zh-v1.5 \
  uvx --with chromadb --with sentence-transformers python3 Core/chroma_helper.py
```

> `BAAI/bge-base-zh-v1.5` (400MB) is recommended for better Chinese results with less latency. Switch via the `SCREAM_LIFE_EMBEDDING_MODEL` environment variable; automatically falls back to TF-IDF when offline.

---

## 🏗 Architecture

```
┌──────────────────────────────────────────────┐
│         Any MCP-Compatible Agent              │
│   (any MCP-compatible agent)     │
└──────────────────┬───────────────────────────┘
                   │ MCP Protocol (stdio / NDJSON)
                   ▼
┌──────────────────────────────────────────────┐
│            ScreamLife MCP Server              │
│               (8 tools)                       │
├──────────────────────────────────────────────┤
│  scream-save    → user decision capture       │
│  scream-search  → 3-layer retrieval           │
│  scream-bias    → 8 bias detection            │
│  scream-advice  → history-based advice        │
├──────────────────────────────────────────────┤
│  SQLite (decisions / patterns / identity)     │
│  Chroma (vector index, auto-embedding)        │
│  AGENTS.md (auto-generated context)           │
└──────────────────────────────────────────────┘
```

---

## 📁 Project Structure

```
scream-life/
├── .mcp.json              ← MCP config entry
├── package.json
├── deploy.sh              ← One-click deploy
├── Core/
│   ├── mcp-server.ts      ← MCP Server (8 tools, NDJSON)
│   ├── database.ts        ← SQLite storage + FTS5
│   ├── search.ts          ← 3-layer search engine
│   ├── chroma-client.ts   ← Chroma vector client
│   ├── chroma_helper.py   ← Chroma Python helper
│   ├── analyzer.ts        ← Bias detection + pattern mining
│   ├── advisor.ts         ← Decision advice engine
│   ├── transcript-watcher.ts ← Real-time capture
│   ├── migrations.ts      ← Schema versioned migrations
│   ├── logger.ts          ← Structured JSON logging
│   └── middleware/rate-limit.ts ← API rate limiting
├── Web/
│   ├── server.ts          ← Web gateway (API + SSE)
│   └── public/            ← Frontend (glassmorphism UI)
├── hooks/                 ← Hook integration
└── tests/                 ← Test suite
```

---

## 🛡 Security

- **SQL injection** — column whitelist on all updates
- **Path traversal** — resolved-path boundary checks
- **XSS** — full HTML entity escaping (incl. quotes)
- **Rate limiting** — per-client token bucket
- **Decision validation** — agent-voice exclusion + user-decision signal check

---

## 🧰 Tech Stack

| Layer | Technology |
|---|---|
| Runtime | Bun + TypeScript |
| Storage | SQLite + FTS5 |
| Vector | Chroma + auto-embedding |
| Protocol | MCP (JSON-RPC 2.0 over stdio) |
| Web | Bun.serve + SSE |
| UI | Vanilla JS + Glassmorphism |

---

## 📦 Version

**v0.1.0** · 2026-07-31

---

<p align="center">
  <sub>Built for the AGI era — a decision system that AI cannot replace.</sub>
</p>