A distributed hybrid vector and graph database designed as an LLM long-term memory backend with human visibility layers. Built in Zig with Raft consensus for reliability, MCP integration for LLM access, and Cypher-like queries for human exploration.

Memora serves as a dual-purpose memory architecture:

🤖 For LLMs: High-performance semantic memory store via Model Context Protocol (MCP)
👨‍💻 For Humans: Transparent, queryable knowledge graph with web UI and audit capabilities

┌────────────────────────────────────────────────────────────────┐
│                         Memora System                          │
├────────────────────────────────────────────────────────────────┤
│  Access Layer                                                  │
│  ┌─────────────────┐  ┌──────────────────┐ ┌─────────────────┐ │
│  │   MCP Server    │  │   Web UI         │ │ Cypher-like QL  │ │
│  │ (LLM Interface) │  │ (Human Insight)  │ │ (Dev Queries)   │ │
│  └─────────────────┘  └──────────────────┘ └─────────────────┘ │
├────────────────────────────────────────────────────────────────┤
│  Consensus Layer (Raft Protocol)                               │
│  ┌─────────────────┐  ┌──────────────────┐ ┌─────────────────┐ │
│  │ Leader Election │  │ Log Replication  │ │ Fault Tolerance │ │
│  │ (150-300ms)     │  │ (TCP + CRC32)    │ │ (Majority)      │ │
│  └─────────────────┘  └──────────────────┘ └─────────────────┘ │
├────────────────────────────────────────────────────────────────┤
│  Memory Layer                                                  │
│  ┌─────────────────┐  ┌──────────────────┐ ┌─────────────────┐ │
│  │ Concept Graph   │  │ Semantic Vectors │ │ Memory Cache    │ │
│  │ (Knowledge Web) │  │ (Similarity)     │ │ (LRU + LFU)     │ │
│  └─────────────────┘  └──────────────────┘ └─────────────────┘ │
├────────────────────────────────────────────────────────────────┤
│  Storage Layer                                                 │
│  ┌─────────────────┐  ┌──────────────────┐ ┌─────────────────┐ │
│  │  Graph Index    │  │  Vector Index    │ │ Experience Log  │ │
│  │ (Memory-Mapped) │  │ (HNSW Structure) │ │ (Replicated)    │ │
│  └─────────────────┘  └──────────────────┘ └─────────────────┘ │
├────────────────────────────────────────────────────────────────┤
│  Persistence Layer                                             │
│  ┌─────────────────┐  ┌──────────────────┐ ┌─────────────────┐ │
│  │ Memory Snapshots│  │ Network Protocol │ │ S3 Sync         │ │
│  │ (Event Sourcing)│  │ (Binary + CRC32) │ │ (Snapshots)     │ │
│  └─────────────────┘  └──────────────────┘ └─────────────────┘ │
└────────────────────────────────────────────────────────────────┘

# Health check and memory stats
curl http://localhost:8080/api/v1/health

# Store data
curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{"id": 100, "label": "UserPreference"}'

# Query relationships
curl http://localhost:8080/api/v1/nodes/1/related

# Vector similarity
curl http://localhost:8080/api/v1/vectors/1/similar

# Hybrid queries
curl -X POST http://localhost:8080/api/v1/query/hybrid \
  -H "Content-Type: application/json" \
  -d '{"node_id": 1, "depth": 2, "top_k": 5}'

# Start MCP server
zig build mcp-server --port 9090

# LLMs connect via MCP protocol
# Supports all MCP v1.0 capabilities:
# - Resource discovery
# - Tool invocation  
# - Streaming responses
# - Bidirectional communication

• Zig 0.14+ - Install Zig
• MCP-compatible LLM - Claude, GPT-4, or custom implementation

# Clone Memora
git clone <repo-url> memora
cd memora

# Build and start HTTP server
zig build http-server

# Or start MCP server for LLM integration
zig build mcp-server

# Servers run on localhost:8080 (HTTP) and localhost:9090 (MCP)

const std = @import("std");
const Memora = @import("src/main.zig").Memora;
const types = @import("src/types.zig");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const config = Memora.MemoraConfig{
        .data_path = "memora_data",
        .enable_persistent_indexes = true,
    };

    var db = try Memora.init(allocator, config);
    defer db.deinit();

    // Store knowledge as nodes, edges, vectors
    try db.insertNode(types.Node.init(1, "UserPreference"));
    try db.insertEdge(types.Edge.init(1, 2, types.EdgeKind.related));
    
    const related = try db.queryRelated(1, 2);
    defer related.deinit();
}

// Node: Graph vertex with ID and label
const Node = packed struct {
    id: u64,
    label: [32]u8,
};

// Edge: Graph connection with relationship type
const Edge = packed struct {
    from: u64,
    to: u64,
    kind: u8, // EdgeKind enum value
};

// Vector: 128-dimensional embedding
const Vector = packed struct {
    id: u64,
    dims: [128]f32,
};

const EdgeKind = enum(u8) {
    owns = 0,
    links = 1,
    related = 2,
    child_of = 3,
    similar_to = 4,
};

// Find nodes within N hops
const related = try db.queryRelated(start_node_id, depth);

// Hybrid graph+vector queries
const hybrid_result = try db.queryHybrid(start_node_id, depth, top_k);
defer hybrid_result.deinit();

// Find K most similar vectors
const similar = try db.querySimilar(vector_id, top_k);

memora/
├── metadata/
│   ├── snapshot-000001.json
│   ├── snapshot-000002.json
│   └── snapshot-000003.json
├── vectors/
│   ├── vec-000001.blob       # Binary vector data
│   ├── vec-000002.blob
│   └── vec-000003.blob
├── nodes/
│   ├── node-000001.json      # JSON node data
│   ├── node-000002.json
│   └── node-000003.json
├── edges/
│   ├── edge-000001.json      # JSON edge data
│   ├── edge-000002.json
│   └── edge-000003.json
└── memora.log               # Append-only binary log

# Start 3-node cluster
# Node 1 (Leader)
zig build run-distributed -- --node-id=1 --port=8001

# Node 2 (Follower)  
zig build run-distributed -- --node-id=2 --port=8001

# Node 3 (Follower)
zig build run-distributed -- --node-id=3 --port=8001

• Strong Consistency: All writes replicated via Raft consensus
• Read Scaling: Can read from any node for performance
• Partition Tolerance: Continues operating with majority of nodes
• Automatic Recovery: Failed nodes catch up automatically when rejoining

# Run all tests
zig build test-all

# Test specific components
zig build test-raft          # Distributed consensus tests
zig build test-partitioning  # Data partitioning and consistent hashing tests
zig build test               # Core database tests  
zig build test-http-api      # HTTP REST API tests

# Fuzzing campaigns
zig build fuzz-quick         # Quick fuzzing (50 iterations)
zig build fuzz-stress        # Stress testing with large datasets

# Run distributed demo
zig build demo-distributed   # Interactive cluster demonstration
zig build gossip-demo        # Automatic node discovery demo

• Nodes/Vectors: Tested with 100K+ items
• Concurrent Connections: HTTP server handles 1000+ connections
• Memory Usage: Efficient memory-mapped indexes
• Storage: Compressed snapshots with S3 sync

Core database infrastructure with deterministic, append-only architecture

• ✅ Graph Database Core - Node/edge storage with adjacency lists and HNSW vector indexing
• ✅ Vector Search Engine - 128-dimensional embeddings with cosine similarity and O(log n) performance
• ✅ Deterministic Database - Append-only WAL, atomic transactions, snapshot consistency
• ✅ Query Optimization Engine - Intelligent query planning and caching
• ✅ Caching System - High-performance memory access with LRU/LFU policies
• ✅ Parallel Processing System - Multi-threaded operations with load balancing
• ✅ Memory-Mapped Persistent Indexes - Instant startup via disk-backed indexes
• ✅ HTTP REST API - Production-ready web API for programmatic access
• ✅ Monitoring & Metrics - Comprehensive operation observability
• ✅ Advanced Configuration System - Production-ready configuration management

Semantic memory types optimized for LLM workflows instead of generic nodes

• ✅ LLM Memory Data Models - 10 semantic types: experience, concept, fact, decision, observation, preference, context, skill, intention, emotion
• ✅ Confidence & Importance Tracking - 5-level granular metadata for memory relevance and reliability
• ✅ Memory Sources & Provenance - Track origin: user_input, llm_inference, system_observation, external_api, computed
• ✅ Semantic Relationships - 8 relationship types: similar_to, caused_by, supports, contradicts, co_occurred, sequence, contains, derives_from
• ✅ LLM Session Management - Group memories by conversation/context with metadata tracking
• ✅ Advanced Memory Querying - Filter by type, confidence, importance, session, time ranges
• ✅ Model Context Protocol (MCP) Server - Native MCP v2.0 implementation with semantic memory tools
• ✅ Memory Statistics & Analytics - Distribution tracking and usage patterns

Demo: Run zig build llm-memory-demo to see semantic memory storage and retrieval

Automatic node discovery and cluster formation without manual configuration

• ✅ Gossip Protocol Implementation - Epidemic-style node discovery with failure detection
• ✅ Automatic Bootstrap - Zero-configuration cluster formation using seed nodes
• ✅ Node Health Monitoring - Heartbeat-based failure detection and recovery
• ✅ Dynamic Membership - Nodes can join/leave clusters automatically
• ✅ Raft Integration - Discovered nodes automatically form Raft consensus clusters
• ✅ Raft Protocol Implementation - Leader election, log replication, membership changes
• ✅ Node Discovery - Automatic cluster formation and health monitoring
• ✅ Data Partitioning - Consistent hashing for horizontal scaling with virtual nodes, load balancing, and automatic rebalancing
• ✅ Failover & Recovery - Automatic leader failover, node recovery, state synchronization, and data repair
• ✅ Conflict Resolution - Split-brain protection, vector clock conflict detection, and network partition handling

Tools for humans to understand and manage LLM memory systems

• MemQL Query Language - Cypher-like syntax for memory exploration and debugging
• Web UI Memory Dashboard - Visual memory timeline, concept graphs, decision audit trails
• Memory Audit & Curation Tools - Human interfaces for inspecting and correcting LLM memories
• LLM Decision Provenance Tracking - Trace responses back to specific memory evidence

Enterprise-grade memory management and monitoring

• Structured Memory Logging - Professional debugging and audit trails for memory operations
• Memory Lifecycle Management - Automatic cleanup, archival, and importance-based retention
• Multi-Tenant Memory - Isolated memory spaces for different LLMs/users/projects
• Memory Analytics & Insights - Understanding LLM learning patterns and memory utilization

Next-generation semantic memory capabilities

• Memory Compression & Summarization - Intelligent memory consolidation for long-term storage
• Cross-Model Memory Sharing - Secure memory exchange between different LLM instances
• Temporal Memory Reasoning - Time-aware memory retrieval and concept evolution tracking
• Memory Contradiction Detection - Identify and resolve conflicting memories automatically

Massive scale deployment and bulletproof reliability

• Horizontal Memory Sharding - Distribute massive memory datasets across nodes
• Real-time Memory Replication - Writer-reader replication with memory consistency guarantees
• Memory Backup & Recovery - Point-in-time memory restoration and disaster recovery
• Advanced Memory Security - Encryption, access control, and memory privacy protection

• 📚 Long-term Conversational Memory - Remember user preferences, context, and history across sessions
• 🧠 Knowledge Accumulation - Build persistent knowledge from multiple interactions and sources
• 🔍 Contextual Decision Making - Access relevant past experiences for better current responses
• 📈 Learning & Adaptation - Track what works, what doesn't, and evolve interaction patterns
• 🔗 Cross-Domain Knowledge Transfer - Apply insights from one domain to related problems
• 🎯 Personalization - Adapt communication style and content based on stored user models

1. Fork the Memora repository
2. Create a feature branch focused on LLM memory capabilities
3. Add comprehensive tests including integration scenarios
4. Run zig build test-all
5. Submit a pull request with performance benchmarks

• Memory First: All features should enhance LLM memory capabilities
• Human Debuggable: Ensure human developers can inspect and understand stored data
• Deterministic: Memory operations must be reproducible for testing
• Performance Critical: Memory retrieval should be sub-millisecond
• Privacy Aware: Design with multi-tenant memory isolation in mind

This project is licensed under the MIT License - see the LICENSE file for details.

• TigerBeetle: Inspiration for deterministic, high-performance memory backend design
• Model Context Protocol (MCP): Standard for LLM tool integration and memory access
• Apache Iceberg: Inspiration for immutable, time-travel capable memory snapshots
• Zig Community: For the amazing language perfect for system-level LLM infrastructure

Memora: Building the memory layer for the age of AI 🧠✨

Vibe-coded with ❤️ by AIs and humans, for AIs and humans.