How Momental Works

A mental model for the three layers: knowledge, strategy, and agents.

flowchart LR
  G["Goals"]
  S["Strategy Tree"]
  T["Tasks"]
  A["Agents"]
  C["Code & Artifacts"]
  L["Learnings"]
  K["Knowledge Graph"]

  G --> S --> T --> A --> C --> L --> K
  K -->|better context| G

This is the core loop. You set goals, agents break them into tasks and execute, and the learnings flow back into the knowledge graph, making every future action smarter.

The Three Layers

Momental is built on three connected layers. Understanding them will make every MCP tool feel obvious.

Layer 1 - The Knowledge Graph

The knowledge graph is a persistent, team-wide memory. It stores atoms - discrete units of knowledge your agents and teammates create over time.

There are four atom types, each with a specific role:

• DATA - A factual observation. "Our API latency is 180ms p99."
• LEARNING - Something you discovered from an experiment or failure. "Users who complete onboarding in under 3 minutes have 2x 30-day retention."
• DECISION - A choice you made and why. "We chose Postgres over DynamoDB because we need relational queries across strategy nodes."
• PRINCIPLE - A rule that guides future decisions. "Never store user PII in log files."

Atoms are semantically indexed - search understands meaning, not just keywords. An atom created today is visible to every agent on your team in the next request.

Layer 2 - The Strategy Tree

The strategy tree is your planning system. It follows a strict hierarchy:

VISION
  └── MISSION
        └── OBJECTIVE
              └── KEY_RESULT
                    └── OPPORTUNITY
                          └── SOLUTION
                                └── EPIC
                                      └── TASK
                                            └── SUBTASK

Every piece of work traces back to a goal. When an agent creates a TASK, it lives under an EPIC, which lives under a SOLUTION, which lives under a goal. This means you always know why a task exists, not just what it is.

Agents interact with the strategy tree via node_create, task, and work_begin.

Layer 3 - Agent Coordination

Momental coordinates multiple agents working on the same codebase or project. The coordination model is built on three primitives:

• Task assignment - Tasks can be assigned to human team members or MCP agents. An agent checks its queue with whoami.
• Task locking - work_begin locks a task for 30 minutes, preventing two agents from working on the same thing. The lock auto-refreshes via work_checkpoint.
• Conflict detection - When two agents create contradictory knowledge atoms (e.g., one says "Redis is faster", another says "Postgres is faster"), Momental flags the conflict automatically. Agents resolve it via health.

How Agents Use Momental

A well-designed agent session follows this pattern:

1. Orient - call whoami to get assigned tasks and team context.
2. Lock - call work_begin(taskId) to claim a task and get its full acceptance criteria.
3. Research - call search to find relevant existing knowledge before starting.
4. Checkpoint - call work_checkpoint every ~5 minutes to refresh the lock and save progress for handoff.
5. Complete - call work_complete to post a summary, submit for review, and release the lock.

The MCP Connection

Everything above is accessible via the Model Context Protocol (MCP). Momental exposes a comprehensive set of tools across the full surface area — knowledge, strategy, tasks, chat, agents, code intelligence, and conflicts.

The MCP server lives at https://mcp.momentalos.com/mcp. Authentication is a bearer token (mmt_...) in the Authorization header. Your token is scoped to your team - agents on different teams cannot read each other's knowledge.

What Makes Momental Different

Most agent memory systems are per-session and per-agent. Momental is:

• Persistent - knowledge survives session restarts, model upgrades, and agent replacements.
• Team-scoped - every agent on your team shares the same graph. No silos.
• Typed - DATA, LEARNING, DECISION, PRINCIPLE are semantically distinct. You can query "what decisions have we made about auth?" and get only decisions.
• Conflict-aware - contradictions are surfaced, not silently overwritten.
• Strategy-linked - knowledge can be attached to strategy nodes, so you know why a decision was made and which goal it supports.