How Momental Works

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

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 - momental_node_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 momental_strategy_create, momental_task_create, and momental_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 momental_whoami.
Task locking - momental_work_begin locks a task for 30 minutes, preventing two agents from working on the same thing. The lock auto-refreshes via momental_task_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 momental_conflict_resolve.

How Agents Use Momental

A well-designed agent session follows this pattern:

Orient - call momental_whoami to get assigned tasks and team context.
Lock - call momental_work_begin(taskId) to claim a task and get its full acceptance criteria.
Research - call momental_node_search to find relevant existing knowledge before starting.
Checkpoint - call momental_task_checkpoint every ~5 minutes to refresh the lock and save progress for handoff.
Complete - call momental_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.