Memory & Knowledge

Store decisions, learnings, and facts that persist across sessions and agents.

Knowledge Atoms

An atom is the atomic unit of knowledge in Momental. Every atom has a type that encodes its epistemic role:

• DATA - A measurement or observation. "API p99 latency is 180ms under 1,000 RPS."
• LEARNING - Something discovered from experience. "Caching auth tokens in Redis cut latency 40% in our load test."
• DECISION - A choice with rationale. "We chose Postgres over DynamoDB because our queries are relational and we need consistent reads."
• PRINCIPLE - A rule for future choices. "Never store PII in structured logs."

This typing matters for search: momental_node_search({ query: "auth decisions", nodeType: "DECISION" }) returns only decisions, not all mentions of auth.

Creating Atoms

momental_node_create

Creates a knowledge atom. Pass status: "ACTIVE" to make it immediately searchable. The default status is DRAFT, which is excluded from all search results until published.

// Save a learning from a failed experiment
await momental_node_create({
  statement: "Our Redis cache hit rate drops below 20% when TTL is under 60 seconds",
  nodeType: "LEARNING",
  status: "ACTIVE",
  domain: "engineering",
  sourceQuote: "Measured during load testing at 2,000 RPS. Keys evicted too fast to be useful.",
  tags: ["redis", "caching", "performance"]
});

// Record a decision with full rationale
await momental_node_create({
  statement: "We use edge caching (Cloudflare) for public API responses, not Redis",
  nodeType: "DECISION",
  status: "ACTIVE",
  domain: "infrastructure",
  sourceQuote: "Redis adds operational complexity for a small team. Cloudflare cache achieves the same latency goals for our public endpoints without a stateful dependency."
});

Searching Knowledge

momental_node_search

Searches atoms using semantic similarity. Returns atoms ranked by relevance to your query. Excludes DRAFT atoms by default - only searches ACTIVE atoms.

// Find all decisions about authentication
const decisions = await momental_node_search({
  query: "authentication and authorization decisions",
  nodeType: "DECISION",
  limit: 5
});

// Find learnings related to performance
const learnings = await momental_node_search({
  query: "what have we learned about API latency and caching",
  nodeType: "LEARNING",
  domain: "engineering"
});

momental_browse_knowledge

Browse atoms without a search query - useful for reviewing recent additions or scanning a domain.

Linking Atoms

momental_node_link

Creates a directed relationship between two atoms. This is how you build a knowledge graph - not just isolated facts, but connected understanding.

Persistent Agent Memory

momental_remember

Saves an observation to the agent's persistent memory. Use for corrections and preferences that should apply to every future session. Two tiers:

• pinned (auto-assigned for correction and preference types) - always returned, never decayed
• active - returned based on relevance, may be archived over time

momental_recall

Retrieves persistent agent memory. Returns pinned observations (always), plus active memories ranked by recency and relevance. Call at session start alongside momental_whoami.

momental_context

Session-start primer. Returns all pinned observations unconditionally - corrections and preferences your agent should always follow. No parameters.

Document Ingestion

Use the document tools to bulk-ingest knowledge from existing text - design docs, meeting notes, post-mortems, API specs. Momental extracts atoms automatically (~1–2 minutes per document).

momental_document_add

Submit a document for extraction. Returns a documentId to check status.

momental_document_publish

Promotes extracted atoms from DRAFT to ACTIVE, making them searchable. After calling momental_document_add and waiting for extraction, call this to publish.

// Ingest a post-mortem document
const { documentId } = await momental_document_add({
  title: "Auth outage post-mortem 2026-03-15",
  content: postMortemText,
  domain: "engineering"
});

// Wait for extraction (~1-2 minutes), then check
const status = await momental_document_status({ documentId });
console.log(status.atomCount); // How many atoms were extracted

// Publish when ready
await momental_document_publish({ documentId });
// Extracted atoms are now searchable by all agents

Quick Reference