memory-fabric

Memory Fabric - Graph Orchestration

Knowledge graph orchestration via mcp__memory__* for entity extraction, query parsing, deduplication, and cross-reference boosting.

Overview

• Comprehensive memory retrieval from the knowledge graph
• Cross-referencing entities within graph storage
• Ensuring no relevant memories are missed
• Building unified context from graph queries

Architecture Overview

Memory Fabric Layer
┌─────────────┐ ┌──────────────┐
│Query Parser │ │Query Executor│
└──────┬──────┘ └──────┬───────┘
       └───────┬───────┘
┌──────────────┴─────────────┐
│Graph Query Dispatch        │
└──────────────┬─────────────┘
┌──────────────┴─────────────┐
│mcp__memory__*              │
│(Knowledge Graph)           │
└──────────────┬─────────────┘
┌──────────────┴─────────────┐
│Result Normalizer           │
└──────────────┬─────────────┘
┌──────────────┴─────────────┐
│Deduplication Engine        │
│(>85% sim)                  │
└──────────────┬─────────────┘
┌──────────────┴─────────────┐
│Cross-Reference Booster     │
└──────────────┬─────────────┘
┌──────────────┴─────────────┐
│Final Ranking: recency ×    │
│relevance × source_authority│
└────────────────────────────┘

Unified Search Workflow

Step 1: Parse Query

Extract search intent and entity hints from natural language:

Input: "What pagination approach did database-engineer recommend?"

Parsed:
- query: "pagination approach recommend"
- entity_hints: ["database-engineer", "pagination"]
- intent: "decision" or "pattern"

Step 2: Execute Graph Query

Query Graph (entity search):

mcp__memory__search_nodes({
  query: "pagination database-engineer"
})

Step 3: Normalize Results

Transform results to common format:

{
  "id": "graph:original_id",
  "text": "content text",
  "source": "graph",
  "timestamp": "ISO8601",
  "relevance": 0.0-1.0,
  "entities": ["entity1", "entity2"],
  "metadata": {}
}

Step 4: Deduplicate (>85% Similarity)

When two results have >85% text similarity:

1. Keep the one with higher relevance score
2. Merge metadata
3. Mark as "cross-validated" for authority boost

Step 5: Cross-Reference Boost

If a result mentions an entity that exists elsewhere in the graph:

• Boost relevance score by 1.2x
• Add graph relationships to result metadata

Step 6: Final Ranking

Score = recency_factor × relevance × source_authority

Factor	Weight	Description
recency	0.3	Newer memories rank higher
relevance	0.5	Semantic match quality
source_authority	0.2	Graph entities boost, cross-validated boost

Result Format

{
  "query": "original query",
  "total_results": 4,
  "sources": {
    "graph": 4
  },
  "results": [
    {
      "id": "graph:cursor-pagination",
      "text": "Use cursor-based pagination for scalability",
      "score": 0.92,
      "source": "graph",
      "timestamp": "2026-01-15T10:00:00Z",
      "entities": ["cursor-pagination", "database-engineer"],
      "graph_relations": [
        { "from": "database-engineer", "relation": "recommends", "to": "cursor-pagination" }
      ]
    }
  ]
}

Entity Extraction

Memory Fabric extracts entities from natural language for graph storage:

Input: "database-engineer uses pgvector for RAG applications"

Extracted:
- Entities:
  - { name: "database-engineer", type: "agent" }
  - { name: "pgvector", type: "technology" }
  - { name: "RAG", type: "pattern" }
- Relations:
  - { from: "database-engineer", relation: "uses", to: "pgvector" }
  - { from: "pgvector", relation: "used_for", to: "RAG" }

Load Read("references/entity-extraction.md") for detailed extraction patterns.

Graph Relationship Traversal

Memory Fabric supports multi-hop graph traversal for complex relationship queries.

Example: Multi-Hop Query

Query: "What did database-engineer recommend about pagination?"

1. Search for "database-engineer pagination"
   → Find entity: "database-engineer recommends cursor-pagination"

2. Traverse related entities (depth 2)
   → Traverse: database-engineer → recommends → cursor-pagination
   → Find: "cursor-pagination uses offset-based approach"

3. Return results with relationship context

Integration with Graph Memory

Memory Fabric uses the knowledge graph for entity relationships:

1. Graph search via mcp__memory__search_nodes finds matching entities
2. Graph traversal expands context via entity relationships
3. Cross-reference boosts relevance when entities match

Integration Points

With memory Skill

When memory search runs, it can optionally use Memory Fabric for unified results.

With Hooks

• prompt/memory-fabric-context.sh - Inject unified context at session start
• stop/memory-fabric-sync.sh - Sync entities to graph at session end

Configuration

# Environment variables
MEMORY_FABRIC_DEDUP_THRESHOLD=0.85    # Similarity threshold for merging
MEMORY_FABRIC_BOOST_FACTOR=1.2        # Cross-reference boost multiplier
MEMORY_FABRIC_MAX_RESULTS=20          # Max results per source

MCP Requirements

Required: Knowledge graph MCP server:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/memory-mcp-server"]
    }
  }
}

Error Handling

Scenario	Behavior
graph unavailable	Error - graph is required
Query empty	Return recent memories from graph

Related Skills

• ork:memory - User-facing memory operations (search, load, sync, viz)
• ork:remember - User-facing memory storage
• caching - Caching layer that can use fabric

Key Decisions

Decision	Choice	Rationale
Dedup threshold	85%	Balances catching duplicates vs. preserving nuance
Parallel queries	Always	Reduces latency, both sources are independent
Cross-ref boost	1.2x	Validated info more trustworthy but not dominant
Ranking weights	0.3/0.5/0.2	Relevance most important, recency secondary