Memory Engine

Semantic Memory Storage & Retrieval Engine with Graph-Enhanced B+ Tree and Edge-as-Memory Architecture

A high-performance memory system that treats relationships between chunks as first-class memory components, enabling graph-based semantic search and discovery.

Features

• Edge-as-Memory Architecture: Relationships have their own vectors and can be searched semantically
• Hybrid Search: Combine chunk vector search with edge-based graph traversal
• B+ Tree Indexing: LMDB-backed persistent storage with O(log n) operations
• Semantic Edge Labels: SEMANTIC_SIMILAR, CAUSAL, TEMPORAL_FOLLOWS, and more
• Automatic Edge Creation: Edges built during ingestion with confidence scores
• Graph Expansion: Discover chunks via relationship traversal
• Zero Memory Overhead: LMDB mmap for disk-backed, OS-cached storage
• Python Integration: Sentence transformers for embeddings
• PostgreSQL + pgvector: Advanced vector operations
• Docker Ready: Full CGO + LMDB support in containers

Quick Start

Option 1: Docker (Recommended)

Full edge-as-memory support with CGO + LMDB out of the box

# Build and start all services
docker-compose up -d --build

# Wait for startup (30 seconds)
docker-compose logs -f memory-engine

# Verify health
curl http://localhost:8080/health

# Try it out!
curl -X POST http://localhost:8080/api/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{"content":"AI is transforming technology","source":"test"}'

See: DOCKER_BUILD_RUN.md for complete guide

Option 2: Build (No CGO - Basic Features Only)

.\build.ps1

Or manually:

$env:CGO_ENABLED=0
go build -o memory-engine.exe .

Run Locally (Recommended for Development)

.\run.ps1

Or manually:

$env:MEMORY_ENGINE_ENVIRONMENT="development"
$env:CGO_ENABLED="0"
.\memory-engine.exe

Run with Docker

$env:DOCKER_BUILDKIT=1
$env:COMPOSE_DOCKER_CLI_BUILD=1
docker-compose -f docker-compose.minimal.yml up --build

Configuration

Edit configs/development.yaml for your needs.

Access

• API: http://localhost:8080
• Health: http://localhost:8080/health

Documentation

Getting Started

• Docker Build & Run Guide - Complete guide to building and running with Docker
• Edge Memory Quick Start - Quick start guide for edge-as-memory features
• Build Guide - Native build instructions (Linux, macOS, Windows)

Architecture & Design

• B+ Tree Edge Architecture - Complete architecture documentation
• Implementation Summary - Implementation details and design decisions
• Graph B+ Tree Implementation - Graph-enhanced B+ tree details

Operations & Deployment

• Docker Build Verification - Verify Docker build correctness
• Testing Guide - Testing strategies and frameworks
• Changelog - Version history and changes

Reference

• Memora Implementation Status - Feature implementation status

API Examples

Standard Search

curl -X POST http://localhost:8080/api/v1/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning applications",
    "max_results": 10,
    "min_relevance": 0.7
  }'

Hybrid Search (NEW!)

curl -X POST http://localhost:8080/api/v1/search/hybrid \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_query": {
      "query": "artificial intelligence",
      "max_results": 10
    },
    "edge_query": {
      "labels": ["SEMANTIC_SIMILAR"],
      "min_confidence": 0.8
    },
    "chunk_weight": 0.6,
    "edge_weight": 0.4,
    "expand_depth": 1
  }'

Edge Operations (NEW!)

# Get edges from a chunk
curl http://localhost:8080/api/v1/edges/from/chunk_123?label=SEMANTIC_SIMILAR

# Search edges by vector
curl -X POST http://localhost:8080/api/v1/edges/search \
  -d '{"query": "causal relationships", "labels": ["CAUSAL"]}'

# Get top confidence edges
curl http://localhost:8080/api/v1/edges/top?k=10

Architecture Overview

┌─────────────────────────────────────────────┐
│         Memory Engine Architecture          │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐      ┌─────────────────┐ │
│  │ Chunk Storage│◄────►│ Edge Storage    │ │
│  │ (B+ Tree)    │      │ (B+ Tree)       │ │
│  └──────────────┘      └─────────────────┘ │
│         ▲                      ▲            │
│         │                      │            │
│         ▼                      ▼            │
│  ┌──────────────────────────────────────┐  │
│  │   Hybrid Search Engine               │  │
│  │ • Chunk vector search                │  │
│  │ • Edge vector search (NEW!)          │  │
│  │ • Graph expansion (NEW!)             │  │
│  │ • Combined ranking                   │  │
│  └──────────────────────────────────────┘  │
│                   ▲                         │
│                   │                         │
│         REST API (Port 8080)                │
└─────────────────────────────────────────────┘

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines (TODO).

License

MIT License - see LICENSE file for details.