Cookbook: Query the Knowledge Graph

Search your team's stored knowledge, retrieve relevant decisions and learnings, and use them to inform agent responses.

What This Recipe Does

  1. Connects to Momental via HTTP MCP transport
  2. Identifies the current agent and workspace
  3. Runs a semantic search against the knowledge graph
  4. Filters results by atom type (DECISION)
  5. Displays the results with source context

Expected time to complete: under 5 minutes from a working MCP connection.

Prerequisites

Step 1: Configure the MCP Connection

Add Momental to your MCP client config. This example uses Claude Code, but any MCP-compatible client works the same way. 

// ~/.cursor/mcp.json  (Cursor IDE)
// ~/.claude/mcp.json  (Claude Code)
{
  "mcpServers": {
    "momental": {
      "url": "https://mcp.momentalos.com/mcp",
      "headers": {
        "X-Api-Key": "mmt_your_key_here",
        "X-Agent-Id": "your-agent-id"
      }
    }
  }
}

Step 2: Verify the Connection

Call momental_whoami to verify you are connected to the right workspace. If you see a different workspace than expected, check that your API key matches the intended workspace. 

const me = await momental_whoami();
console.log(me.teamName);   // "Acme Engineering"
console.log(me.agentType);  // "coding-tool"

Step 3: Run a Semantic Search

Use momental_node_search to search the knowledge graph with a natural language query. The search uses semantic similarity - you do not need to know exact keywords. 

const results = await momental_node_search({
  query: "authentication decisions",
  nodeType: "DECISION",
  limit: 10
});

for (const atom of results) {
  console.log(`[${atom.type}] ${atom.statement}`);
  if (atom.description) {
    console.log(`  Context: ${atom.description}`);
  }
  console.log(`  Domain: ${atom.domain ?? "unspecified"}`);
  console.log();
}

Step 4: Browse Without a Query

When you want to explore recent activity rather than search for something specific, use momental_browse_knowledge. It returns recently active atoms, filtered optionally by domain or type. 

const recent = await momental_browse_knowledge({
  domain: "engineering",
  limit: 20
});

// Returns most recently created or accessed atoms in the engineering domain
for (const atom of recent) {
  console.log(`${atom.type}: ${atom.statement}`);
}

Step 5: Follow Connections

Atoms can be linked to strategy nodes (tasks, EPICs) and to other atoms. Use momental_node_read to fetch a specific atom and see its links. 

// Read a specific atom to see its links and full context
const atom = await momental_node_read({ id: results[0].id });

console.log(atom.statement);
console.log(`Linked to ${atom.links.length} nodes`);
for (const link of atom.links) {
  console.log(`  → ${link.rel}: ${link.nodeId}`);
}

Step 6: Save New Knowledge

After reading or working on something, save relevant learnings back to the graph. Knowledge you save is immediately searchable by other agents and team members. 

await momental_node_create({
  statement: "JWT refresh endpoints must validate against the database, not just the token signature - revocation must be enforced server-side",
  nodeType: "LEARNING",
  status: "ACTIVE",
  domain: "engineering",
  sourceQuote: "Discovered during security audit: token signing keys validate authenticity but cannot revoke already-issued tokens. Server-side lookup is required for immediate revocation.",
  tags: ["auth", "security", "jwt"]
});

Common Patterns

Load decisions before starting a task

// Before implementing, check what decisions already exist in this area
const decisions = await momental_node_search({
  query: `${taskTitle} ${taskDomain}`,
  nodeType: "DECISION",
  limit: 5
});

if (decisions.length > 0) {
  console.log("Relevant decisions:");
  decisions.forEach(d => console.log(`  - ${d.statement}`));
}

Use momental_context for a pre-synthesized brief (v2)

On the v2 endpoint, momental_context returns a pre-synthesized brief of the most relevant knowledge for your current work - no manual filtering needed. 

// v2 endpoint: https://mcp.momentalos.com/mcp/v2
const ctx = await momental_context();
// Returns a prose brief: current task context + relevant decisions + open conflicts

Persist a shorthand memory with momental_remember

// For quick, conversational memory (not a formal atom)
await momental_remember({
  key: "preferred_pagination_style",
  value: "cursor-based, not offset - see task #1234 for rationale"
});

// Retrieve later
const pref = await momental_recall({ key: "preferred_pagination_style" });