feat(mcp): add temporal graph support to MCP tools

[kishan0725]

Add Temporal Graph Support to MCP Tools

🎯 Summary

Exposes OpenMemory's temporal graph capabilities through MCP, enabling agents to store and query structured facts that change over time alongside contextual/HSG memories.

💡 Motivation

While OpenMemory has powerful temporal graph features for tracking facts over time (like Zep's Graphiti), these capabilities were only accessible via HTTP API. This PR brings temporal graph support to the MCP interface, allowing Claude, Cursor, Windsurf, and other MCP clients to leverage both:

1. HSG Contextual Memory - Rich semantic memory with sectors
2. Temporal Facts - Structured facts with automatic invalidation and historical queries

This enables agents to handle evolving information like:

• User preferences that change ("prefers Excel" → "prefers PDF")
• Business rules that evolve ("approval at $50K" → "approval at $75K")
• Historical queries ("What was the threshold in Q3?")

🔧 Changes

1. Database (Postgres Support for Temporal Graph)

File: packages/openmemory-js/src/core/db.ts

• ✅ Added temporal_facts table creation for Postgres
• ✅ Added temporal_edges table creation for Postgres
• ✅ Added 7 indexes for efficient temporal queries
• ✅ SQLite already had these tables; now Postgres parity achieved

2. Enhanced MCP Tools

File: packages/openmemory-js/src/ai/mcp.ts

openmemory_store enhancements:

• Added type parameter: "contextual" (default), "factual", "both"
• Added facts array parameter for structured fact storage
• Backward compatible: calls without type default to HSG (contextual)
• Supports automatic fact invalidation (duplicate subject+predicate)

openmemory_query enhancements:

• Added type parameter: "contextual" (default), "factual", "unified"
• Added fact_pattern parameter for temporal queries (subject/predicate/object with wildcards)
• Added at parameter for point-in-time historical queries
• Backward compatible: calls without type use HSG semantic search
• Unified type runs parallel queries to both systems

3. Documentation

File: docs/mcp.md

• Complete API reference for both tools
• Usage examples for all storage/query types
• Response format specifications
• Agent integration guidelines
• Best practices for fact naming conventions
• Troubleshooting guide

📋 API Examples

Storage

// Backward compatible (default: HSG only)
openmemory_store({ content: "User prefers quarterly reports" })

// Store temporal fact
openmemory_store({
  content: "Client prefers Excel format",
  type: "factual",
  facts: [{
    subject: "client_acme",
    predicate: "prefers_report_format",
    object: "Excel"
  }]
})

// Store in both systems
openmemory_store({
  content: "Budget threshold updated to $75K",
  type: "both",
  facts: [{
    subject: "expense_policy",
    predicate: "approval_threshold_usd",
    object: "75000"
  }]
})

Queries

// Backward compatible (default: HSG semantic search)
openmemory_query({ query: "user preferences" })

// Query current facts
openmemory_query({
  query: "client report preferences",
  type: "factual",
  fact_pattern: {
    subject: "client_acme",
    predicate: "prefers_report_format"
  }
})

// Historical query
openmemory_query({
  query: "what was threshold in Q3",
  type: "factual",
  fact_pattern: {
    subject: "expense_policy",
    predicate: "approval_threshold_usd"
  },
  at: "2023-09-30T00:00:00Z"
})

// Unified query (both systems)
openmemory_query({
  query: "client information",
  type: "unified",
  fact_pattern: { subject: "client_acme" }
})

✅ Backward Compatibility

• ✅ No breaking changes: All existing MCP calls work unchanged
• ✅ Optional parameters: type defaults to existing behavior
• ✅ Legacy format support: Parser handles both old and new response formats
• ✅ Graceful degradation: Errors in temporal queries don't break HSG functionality

Benefits

For Users:

• Track evolving preferences and business rules
• Query historical states ("What did I prefer last month?")
• More structured, queryable memory
• Automatic handling of fact changes

For Developers:

• Clean separation: contextual vs. factual storage
• Backward compatible integration
• Type-safe fact structure
• Comprehensive documentation

Migration Notes

No migration needed. This is additive - existing HSG functionality unchanged.

To use new features, agents should:

1. Add type parameter to openmemory_store calls when storing facts
2. Provide facts array with subject-predicate-object triples
3. Use type="factual" or type="unified" for temporal queries
4. Construct fact_pattern for targeted fact retrieval

Example Output

Query: "gitlab mcp project preferences"
Type: unified

Results:
- 8 contextual memories (conversations, context)
- 5 temporal facts (structured preferences)

Both returned in single call for comprehensive context.

Memory/Facts Creation

Memory/Facts Retrieval

[nullure]

LGTM

[kishan0725]

@nullure, can we release a new version in the npm package?

[nullure]

@nullure, can we release a new version in the npm package?

Definatly