Skip to content
BranchesTags

Repository files navigation

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

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

About

A human decision memory system that records, analyzes, and advises on decisions, usable in any agent via the MCP service.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages