MAMA
Documentation · Your first day · How it works · What you can connect · Security · Roadmap
MAMA is a work agent that runs on your own computer. It follows the conversations, files and schedules in the tools you connect, keeps them as they were, and keeps a history of each piece of work: what changed, why, who did it and what the feedback was. You talk to it in your messenger. It answers from that history, sends you reports, and remembers how you want things done.
The same repository also gives Claude Code a development memory (decisions and checkpoints that survive a new session), and both are built on mama-core, a shared engine other products can use.
MAMA runs no hosted service. The record stays on your machine. Only the content a run needs leaves it, through the AI CLI you logged into and the services you connected.
Why
An assistant is only as useful as what it remembers, and memory kept on someone else's server disappears when the service changes. MAMA keeps the record of your work on your computer, in its original form, so today's model and a better one tomorrow can read the same history. You decide which sources to connect and what to hand over.
Principles
In order of importance.
- Never lose the record. Original text, time, source and every later change are kept, not overwritten.
- Know why it changed. Each change to a piece of work names the message or file behind it.
- Act only where allowed. MAMA sends only to the destinations you configured and to the DMs of people you registered, and its agent writes files only inside its own workspace.
- Remember corrections. Say "reports should be short" or "translate feedback into the usual spreadsheet" once. MAMA keeps it as guidance or as a workflow and applies it from then on.
- Stay independent of the model vendor. Claude or Codex runs the agent; the record's format does not depend on either.
- Everything else. Speed and convenience improve only within the five above.
What it looks like
You: Who is working on what right now?
MAMA: 12 items are in progress. Two need you today: the sample poster review is waiting for your decision on the color variant, and the launch checklist is overdue since yesterday 17:00.
You: From now on, when feedback arrives as a PDF, translate it into our feedback spreadsheet and send it back as a file.
MAMA: Saved as a workflow. I will use it for the next feedback PDF.
You (in your DM): Open the progress sheet in Drive and chart this month's prices by title.
MAMA: Here is the chart and the table behind it. Two titles have no price yet this month.
At 08:00, 13:00 and 18:00 it sends a full report. Urgent changes arrive as soon as they happen; the rest are gathered into an hourly reminder between 09:00 and 21:00.
Getting started
You need Node.js 22.13+, a signed-in claude or codex CLI, and a Telegram bot in a group
for common changes (Discord and Slack work too). Create that group even for a solo owner;
setup binds it when you send /bind there. Private chats enter personal sessions.
npm install -g @jungjaehoon/mama-os
mama init # asks for settings; tokens are typed at hidden prompts
mama init checks the backend and the bot token first, pairs you through a code the bot sends
you, then registers you as the first owner,
installs the document toolkit the sessions use for office files and charts, and starts MAMA. When
it says MAMA is running, send your bot a message. After an upgrade, run mama tools install again.
To run from a checkout instead, run pnpm install and pnpm build, then use
node packages/standalone/dist/cli/index.js wherever the guides say mama.
Another owner is added with mama register-owner <telegram id> while MAMA is stopped. See
owner setup.
Then send your bot a message. Setup is done when MAMA answers you, not when the process is running. The first-day tutorial walks through connecting a source, asking about work, giving a correction, reports, the viewer and sending files.
Claude Code development memory is separate and needs no daemon: /plugin install mama, or add the
MCP server {"mcpServers":{"mama":{"command":"npx","args":["@jungjaehoon/mama-server"]}}}.
See Claude Code plugin.
How it works
What you connect work sources · a messenger · corrections you give
The agent a common session, a DM session per person and a group session per member, on Claude or Codex
The record SQLite on your machine: originals · work history · guidance · reports · run logs · local search index
The record. Every collected message, file notice or calendar change is stored as an original observation. Work items keep revisions: each one says what changed, why, the evidence it came from and who was involved. Search runs locally over originals, work history and memory.
The agent. The common group, new source changes and scheduled reports reach the common session. It reads the stored work and sources before answering, updates the work history, writes the board and the wiki pages of the work it touched, and can split a large replay window across subagents inside the same turn. A source change gets a short turn that decides whether to tell you and a second turn that records it; MAMA checks the work ledger and orders the record again if it is missing. Every tool call it makes is recorded with the run that made it.
Each person's DM. Everyone you register, owners included, gets a session of their own in a DM with MAMA, with their own records, scheduled jobs, notices and skills. An owner's DM also reads the common records and sources. In a DM, MAMA can run scripts in that person's workspace, make PowerPoint, Word, Excel and PDF files and charts, and, for an owner, read Google Drive sheets. A member without the owner role works in the group in a session of its own, within the projects it is given. See People and DMs.
Guidance and workflows. Your corrections are kept as lessons, preferences, constraints and workflows, each with a line saying when it applies. Rules that always apply go in your owner policy file, which the common session and owners' DMs hold. With each message from you or source change, the agent is shown the few saved lessons that match it best, and can add, revise or retire workflows as you agree on them. Every change keeps its history.
The viewer. http://127.0.0.1:3847 shows the board, work items with their history, the memory
graph, the wiki and logs.
What you can connect
Each source is optional; enable the ones you use in ~/.mama/connectors.json or during mama init.
Messengers. You talk to MAMA in Telegram, Discord or Slack. In Telegram, each person you register has a DM with MAMA, and owners and members also use the common group; Discord and Slack keep one owner channel. Messages from anyone else are ignored and logged. You choose which messenger receives reports, notifications and security alerts. See Sources and Messengers.
Security
- Tokens are typed by you at a terminal prompt and stored only in
~/.mama/auth.env(mode 0600). The configuration files hold none, and the agent cannot read MAMA's credential files. - The agent writes only inside its workspace. Files you send it are saved by MAMA into a folder the agent can read but not change.
- Messages, files and pages from other people reach the agent marked as untrusted evidence, never as instructions.
- Work that runs with no one in the conversation (source changes and reports, and the notices and scheduled jobs of people with the owner role) can search the web but opens pages only from sites you list; other members have no web tools. When you ask, the agent on the Claude backend can open any page, and you are told which sites it opened, grouped per site within a minute. The Codex backend searches the web but does not open pages.
- The viewer answers only on your machine (
127.0.0.1) by default and serves read-only pages.
Reaching the viewer from outside. If you expose it through a tunnel:
- Put it behind Cloudflare Access and set
MAMA_CF_ACCESS_ISSUERandMAMA_CF_ACCESS_AUDso MAMA verifies the Access token itself, or setMAMA_AUTH_TOKENfor short tests only. - List your hostnames in
MAMA_VIEWER_HOSTNAMES; requests for other hosts are refused. - Every outside request is logged as a security event, and suspicious ones alert you in your messenger.
Details: Security guide, Viewer.
Packages
These are the current package versions.
Roadmap
MAMA is built in stages, and each stage is judged on real work, not on tests alone. Today it runs on the developer's own Mac. 1.0 is the stage where anyone can install it.
Messengers: Telegram is live; Discord and Slack have not run live yet. Windows is not planned for 1.0.
1.0 progress
Each item, with what is true today and how it is checked, is in the 1.0 work list. Ongoing live checks are in the work plan.
Documentation
- Your first day with MAMA · Owner setup
- Sources · Messengers · People and DMs · Reports and board · Corrections and learning
- CLI · Configuration · Architecture
- Security · Contributing
License
MIT.