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/v3",
      "headers": {
        "X-Api-Key": "mmt_your_key_here"
      }
    }
  }
}

See v3.0 install guide for per-client configs (Claude Desktop, Windsurf, VS Code).

Step 2: Verify the Connection

Call 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 whoami({ mode: "full" });
console.log(me.identity.agentName);   // "My Agent"
console.log(me.identity.teamId);      // "team_xyz"

Step 3: Run a Semantic Search

Use 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 search({
  query: "authentication decisions",
  scope: "atoms",
  nodeType: "DECISION",
  limit: 10
});

for (const atom of results.atoms.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 browse. It returns the strategy or product tree, filtered optionally by type. 

const tree = await browse({
  tree: "strategy",
  detail: "summary",
  domain: "engineering",
  limit: 20
});

// Returns strategy nodes in the engineering domain
for (const node of tree.nodes) {
  console.log(`${node.type}: ${node.statement}`);
}

Step 5: Follow Connections

Atoms can be linked to strategy nodes (tasks, EPICs) and to other atoms. Use 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 node_read({ nodeId: results.atoms.results[0].id, include: ["relationships"] });

console.log(atom.statement);
console.log(`Linked to ${atom.relationships.length} nodes`);
for (const link of atom.relationships) {
  console.log(`  → ${link.linkType}: ${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 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",
  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 search({
  query: `${taskTitle} ${taskDomain}`,
  scope: "atoms",
  nodeType: "DECISION",
  limit: 5
});

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

Persist a shorthand memory with remember

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

// Retrieve later
const pref = await recall({ query: "preferred_pagination_style" });