Scream Life

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):

{
  "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:

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):

{
  "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:

# 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

---

_{Built for the AGI era — a decision system that AI cannot replace.}