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

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.

Related MCP server: AgentRecall

🌟 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

🧩 MCP Tools

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

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

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

📦 Version

v0.1.0 · 2026-07-31