# @jungjaehoon/mama-os

> Bounded, provenance-backed working context for AI agents running on your machine.

## The Problem

Your knowledge is everywhere — Slack threads, email chains, code reviews, meeting notes, spreadsheets, Telegram messages. No human can track all of it. Important decisions get buried. Context gets lost between tools. When you need to make a decision, the information that would help is scattered across ten different apps and three months of history.

This isn't just a memory problem. It's a bounded context problem. You don't just need to
_store_ information — you need something that reads everything, connects the dots, identifies what
matters, proves where it came from, and keeps agents inside the scope they were given.

## What MAMA OS Does

MAMA OS is a local AI runtime that connects to your apps, reads continuously, and turns scattered
records into scoped, auditable context for agents and humans.

**What the agents actually do:**

- **Identify what matters** — Out of thousands of daily messages, surface the decisions, deadlines, and changes that affect your work
- **Connect across sources** — A Slack conversation + a Trello card + an email attachment about the same project are linked automatically
- **Track decision evolution** — Not just what was decided, but what it replaced, what it builds on, and what it contradicts
- **Operate inside envelopes** — Gateway and worker calls carry signed scope boundaries and audit rows
- **Preserve provenance** — Memory writes can point back to source refs, model runs, tool traces, and envelope hashes
- **Search with evidence** — Strict memory search can reject vector-only noise and show which lexical, entity, scope, or graph signals confirmed a result
- **Compile actionable knowledge** — Promoted decisions become an Obsidian wiki: an append-only daily journal plus durable lesson pages that strengthen with evidence
- **Evolve their own triggers** — The operator loop authors triggers from recurring situations, fires them to recall the right memory, and scores them by whether delivered reports actually cite them
- **Brief you proactively** — When you start working, relevant context from all sources is already there — you didn't ask for it

```
Without MAMA:  You read 5 Slack channels, 3 email threads, check Trello,
               re-read old PRs, then try to piece together the full picture.

With MAMA:     Agents already read everything. You get a briefing with
               what changed, what's at risk, and what needs your decision.
```

**This is what local AI agents should do** — read every channel, every thread, every document, every
day, then explain exactly which evidence they used and which permission boundary they were inside.

- **Private by design** — All data stays on your device. Nothing leaves your machine.
- **AI-independent** — Works with Claude, Codex, or any future backend. Your memory outlives any AI provider.

## How It Runs

MAMA OS runs AI agents through each backend's **supported local runtime path**: Claude CLI,
Codex app-server, or Cline's official Hub runtime.

Some third-party agent frameworks (OpenClaw, etc.) use unofficial API access, token extraction, or header spoofing — approaches that violate provider policies and risk account suspension. MAMA OS doesn't do any of that. If you have Claude Code, Codex CLI, or Cline CLI installed and authenticated, MAMA OS uses that backend's supported local runtime path. No token extraction or header spoofing is required.

```bash
# Already have Claude Code installed?
mama start   # That's it. MAMA uses your existing CLI authentication.
```

## How It's Secured

MAMA OS has full system access — so security is not optional, it's foundational.

- **Local-only by default** — Binds to localhost. External access requires explicit tunnel setup with authentication (Cloudflare Zero Trust).
- **Signed runtime envelopes** — Gateway and worker tool calls carry verifiable scope, expiry, and
  actor context before irreversible side effects are allowed.
- **Provenance ledger** — Memory writes, raw refs, model runs, and tool traces can be audited after
  the fact without exposing prompt bodies or hidden connector payloads.
- **5-layer prompt injection defense** — Output sanitization, channel trust boundaries, silent mode for unknown sources, bulk extraction limits. Built from a real incident, not theory.
- **Intrusion detection** — Honeypot traps for scanner probes (`.git`, `.env`, `wp-login.php`), per-IP suspicion scoring, automatic tarpit delays, and IP deny-listing when thresholds are exceeded.
- **Agent permission tiers** — Tier 1 (full access), Tier 2 (read + memory write), Tier 3 (read-only). Each agent only gets the tools it needs.
- **Owner console (v0.22+)** — the `owner_console` role is granted ONLY in an allowlisted telegram chat's 1:1 DM (`telegram.allowed_chats` is the trust anchor). It reads operational artifacts (`board_read`, `audit_findings_read`, `workorder_status`), can browse/download/upload Drive files, OCR and overlay translated image text, send files back to the current Telegram chat, and issue work (`report_request`, `workorder_request`) fire-and-forget. The verified owner gets the complete Drive composition surface and may upload to the folder selected in the active request even when it is not a configured deliverable root. Configured-root capabilities remain available and are validated when supplied; non-owner Drive operations require role permission and configured connector/envelope scope and cannot select arbitrary roots. Uploads and outbound files accept only regular non-symlink files in the private MAMA workspace; memory writes refuse secret-shaped content. On a clean installation, prepare the isolated OCR runtime with `pnpm setup:ocr` and verify it with `pnpm check:ocr`; `MAMA_OCR_PYTHON` can select an equivalent managed runtime. Translated overlays also require a Korean/CJK font: macOS uses Apple SD Gothic Neo, while Ubuntu/Debian should install `fonts-noto-cjk`; other systems can set `MAMA_KOREAN_FONT` to a readable `.ttf`/`.ttc` file. The setup check verifies this dependency instead of failing on the first real overlay. DOCX/XLSX extraction runs in a memory- and time-bounded child process. PDF extraction uses PDFKit on macOS and requires Poppler's `pdftotext` on Linux (`apt install poppler-utils` or the distribution equivalent).
- **Stage-2 workorder pipeline (v0.28+, always on)** — scheduled board/wiki/memory-promotion runs become durable, occurrence-keyed workorders consumed serially on the operator lane; briefs live in `~/.mama/briefs/`. Workers receive built-in, least-privilege Tier-2 Code-Act roles for board, wiki, memory curation, and temporal reconciliation, independent of optional standing-agent configuration. Every worker treats connector evidence as untrusted data rather than instructions. The native ledger remains authoritative for owner tasks and pipeline state. `MAMA_STAGE2_WORKORDERS` is retired: leave it unset (or set `on` for compatibility); explicit `off` or `shadow` values fail startup.
- **Verified temporal effects (opt-in)** — `MAMA_TEMPORAL_RECONCILE=on` requires the always-on workorder consumer, a Claude, Codex, or Cline backend, the trusted `task_temporal_reconcile` tool, and a working worker transport. It scans all open scheduled owner rows once per minute before applying bounded admission caps, and exposes a separate temporal projection that never turns overdue into a workflow status (`closed` reflects terminal lifecycle). Fresh evidence may resolve, finalize, or defer one native owner-task occurrence. Task, generation, authoritative receipt, and workorder completion commit atomically; legacy receipts remain quarantined, every temporal gateway call rechecks active authority, and compiled raw evidence must stay bound to the task source. Shutdown durably pauses temporal attempts before waiting for worker drainage. Model prose is represented in audit rows only by length/SHA-256 references. Default `off` pauses temporal work and preserves existing behavior.
- **Fail-safe shutdown** — When an intrusion cannot be contained, MAMA shuts itself down gracefully rather than operating in a compromised state.

These aren't theoretical protections. The prompt injection defense was built after a real attack where an adversary injected a fake "server failure" message into a monitored channel, causing the AI agent to voluntarily expose system configuration. The IP banning system has blocked actual intrusion attempts in production.

See the full [Security Guide](../../docs/guides/security.md) for Cloudflare Zero Trust setup, token authentication, threat scenarios, agent isolation, and Code-Act sandbox security.

## Quick Start

```bash
# 1. Authenticate one backend (one-time)
claude auth login   # or: codex login
cline auth cline    # for the hosted Cline backend

# 2. Install and start
npx @jungjaehoon/mama-os init --backend cline  # or claude / codex / auto
mama start

# 3. Open the operator board
open http://localhost:3847/viewer
```

**Prerequisites:** Node.js >= 22.13.0, one authenticated backend CLI (Claude, Codex, or Cline), 500MB disk space.

## Connectors (13)

MAMA connects to your apps and extracts structured facts into the memory graph.

```bash
mama connector add slack      # Activate + auth guide
mama connector list           # Status of all connectors
```

| Connector       | Prerequisites                                                                                                                        | Config                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| **Slack**       | Bot Token (api.slack.com → OAuth scopes)                                                                                             | `bot_token`, `app_token`         |
| **Discord**     | Bot Token (discord.com/developers → MESSAGE CONTENT INTENT)                                                                          | `token`, `default_channel_id`    |
| **Telegram**    | Bot Token (@BotFather); text, captions, photos, image documents, and regular documents are accepted                                  | `token`, `allowed_chats`         |
| **Chatwork**    | API Token (account settings)                                                                                                         | `api_token`, `room_ids`          |
| **iMessage**    | macOS only (reads local chat.db)                                                                                                     | No config needed                 |
| **Gmail**       | [gws CLI](https://github.com/nicholasgasior/gws) installed + Google OAuth                                                            | `gws` in PATH                    |
| **Calendar**    | gws CLI installed + Google OAuth                                                                                                     | `gws` in PATH                    |
| **Drive**       | gws CLI installed + Google OAuth; bounded polls continue through change-page backlogs, owner console also has direct file operations | `gws` in PATH                    |
| **Sheets**      | gws CLI installed + Google OAuth                                                                                                     | `gws` in PATH, `spreadsheet_ids` |
| **Notion**      | Integration Token (notion.so/my-integrations)                                                                                        | `api_token`, `database_ids`      |
| **Obsidian**    | [Obsidian](https://obsidian.md) installed + [Obsidian Terminal](https://github.com/polyipseity/obsidian-terminal) plugin enabled     | `vault_path` in config.yaml      |
| **Trello**      | API Key + Token (trello.com/app-key)                                                                                                 | `api_key`, `token`, `board_ids`  |
| **Claude Code** | Claude Code plugin installed                                                                                                         | Automatic via hooks              |

**Google Workspace connectors** (Gmail, Calendar, Drive, Sheets) require the [gws CLI](https://github.com/nicholasgasior/gws) — a Google Workspace command-line tool. Install it, run `gws auth` once for OAuth, then MAMA polls via CLI.

Each connector classifies its source (truth / hub / spoke / reference) for the 3-pass extraction pipeline. Config: `~/.mama/connectors.json`.

For connector polling and preconfigured deliverable roots, enable Drive and declare non-ignored
channels. `folderId` scopes that channel to one folder; `driveId` scopes it to a shared drive. These
roots can issue short-lived destination capabilities, but a verified owner-console request is not
limited to them when it explicitly selects another Drive folder.

```json
{
  "drive": {
    "enabled": true,
    "pollIntervalMinutes": 5,
    "channels": {
      "project-docs": {
        "role": "deliverable",
        "name": "Project docs",
        "folderId": "GOOGLE_DRIVE_FOLDER_ID"
      }
    },
    "auth": { "type": "cli", "cli": "gws", "cliAuthCommand": "gws auth login" }
  }
}
```

## Knowledge Agents

MAMA OS runs specialized agents for knowledge management — not coding (that's what Claude Code does natively).

| Agent               | Role                                                | Requires                                                                                              |
| ------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Conductor**       | Orchestrates other agents, handles user chat        | —                                                                                                     |
| **Dashboard Agent** | Generates project briefings from connected sources  | —                                                                                                     |
| **Wiki Agent**      | Compiles knowledge into Obsidian vault              | [Obsidian](https://obsidian.md) + [Terminal plugin](https://github.com/polyipseity/obsidian-terminal) |
| **Memory Agent**    | Extracts decisions from conversations automatically | —                                                                                                     |

Agents delegate via `delegate()` with skill injection and automatic retry. Configure in `~/.mama/config.yaml`.

## Viewer

One web console at `http://localhost:3847/viewer` (`/` redirects there), opening on the
operator board. PWA-enabled for mobile (add to home screen).

Three groups:

| Group         | View       | What it shows                                                                                    |
| ------------- | ---------- | ------------------------------------------------------------------------------------------------ |
| **Operator**  | Board      | Four agent-published report slots (briefing, action required, decisions, pipeline) live over SSE |
| **Operator**  | Tasks      | The task board fed from your channels                                                            |
| **Operator**  | Triggers   | The trigger loop's library with an owner veto tray                                               |
| **Knowledge** | Memory     | Interactive reasoning graph (1000+ nodes), search, export                                        |
| **Knowledge** | Wiki       | Knowledge base (syncs with Obsidian vault)                                                       |
| **System**    | Runtime    | Read-only runtime truth: backend, model, gateways, health                                        |
| **System**    | Connectors | Connector status and last poll                                                                   |
| **System**    | Logs       | Daemon logs with filtering, pinning, stats, WebSocket and polling                                |

Each view has its own hash route, e.g. `/viewer#operator/tasks?task=42`.

## Gateway Integrations

Run MAMA as a bot in Discord, Slack, Telegram, or Chatwork. Configure via `mama setup` or edit
`~/.mama/config.yaml` directly.

## Architecture

```
Connectors (13)              Gateways (4)
Slack, Gmail, Sheets...      Discord, Slack, Telegram, Chatwork
       |                            |
       v                            v
 3-Pass Extraction          Reactive Runtime Envelopes
       |                    scope, expiry, signature, audit
       +------------+---------------+
                    |
             MAMA Core (mama-memory.db)
             memory, raw refs, model runs,
             tool traces, twin edges, packets
                    |
             +------+------+
             |             |
        Viewer UI     Claude Code Plugin / MCP
```

## CLI

| Command                                      | Description              |
| -------------------------------------------- | ------------------------ |
| `mama init`                                  | Initialize workspace     |
| `mama setup`                                 | Interactive setup wizard |
| `mama start`                                 | Start daemon             |
| `mama stop`                                  | Stop daemon              |
| `mama status`                                | Check status             |
| `mama connector <add\|remove\|list\|status>` | Manage connectors        |

## Configuration

Main config: `~/.mama/config.yaml`

| Variable                  | Default                  |
| ------------------------- | ------------------------ |
| `MAMA_DB_PATH`            | `~/.mama/mama-memory.db` |
| `MAMA_HTTP_PORT`          | `3847`                   |
| `MAMA_WORKSPACE`          | `~/.mama/workspace`      |
| `MAMA_STAGE2_WORKORDERS`  | retired; unset or `on`   |
| `MAMA_TEMPORAL_RECONCILE` | `off`                    |

Timeout tuning lives under `timeouts` in `config.yaml`. The persistent CLI process pool supports:

| Option                               | Default                     | Purpose                                     |
| ------------------------------------ | --------------------------- | ------------------------------------------- |
| `persistent_process_idle_ms`         | `session_ms`                | Reclaim idle backend sessions/processes     |
| `persistent_process_cleanup_ms`      | `session_cleanup_ms`        | How often idle-process cleanup runs         |
| `persistent_process_pending_tool_ms` | `max(4 * idle, 30 minutes)` | Max wait for pending tool-result handshakes |

## Related Packages

| Package                      | Purpose                             |
| ---------------------------- | ----------------------------------- |
| **@jungjaehoon/mama-os**     | Always-on AI runtime (this package) |
| **@jungjaehoon/mama-server** | MCP server for Claude Desktop       |
| **@jungjaehoon/mama-core**   | Shared memory engine                |

## Development

```bash
git clone https://github.com/jungjaehoon-lifegamez/MAMA.git
cd MAMA && pnpm install && pnpm build
pnpm test       # 3000+ tests across all packages
```

## Links

[GitHub](https://github.com/jungjaehoon-lifegamez/MAMA) · [npm](https://www.npmjs.com/package/@jungjaehoon/mama-os) · [Docs](https://github.com/jungjaehoon-lifegamez/MAMA/tree/main/docs) · [Issues](https://github.com/jungjaehoon-lifegamez/MAMA/issues)

## License

MIT

---

**Last Updated:** 2026-04-30