SerialMemory

A temporal knowledge graph memory system for AI applications. SerialMemory provides persistent "second brain" capabilities with semantic search, entity extraction, and relationship tracking—enabling AI agents to maintain context and learn from past interactions.

🎯 Features

• Semantic Search: Find memories by meaning, not keywords, using vector embeddings (1536-dim)
• Entity Extraction: Automatically identify people, organizations, locations, skills, and projects
• Knowledge Graph: Build and traverse relationships between entities for multi-hop reasoning
• Temporal Tracking: Full event sourcing with confidence decay and audit trails
• Multi-Tenant: Complete data isolation with row-level security
• MCP Integration: Claude Desktop (Anthropic) and OpenAI compatibility via Model Context Protocol
• REST API: Full-featured HTTP API for custom integrations
• Self-Hosted: Deploy on your own infrastructure with security hardening

🏗️ Architecture

┌────────────────────────────────────────────┐
│      Client Applications                    │
│  (Claude/Anthropic, OpenAI, Custom Apps)   │
└────────────────┬─────────────────────────┘
                 │
         ┌───────┴────────┬──────────────┐
         ▼                ▼              ▼
    ┌─────────┐  ┌──────────────┐  ┌────────┐
    │   MCP   │  │  REST API    │  │ Admin  │
    │ Server  │  │  (HTTP)      │  │ API    │
    │ Anthropic│  │              │  │        │
    │ OpenAI  │  │              │  │        │
    └────┬────┘  └──────┬───────┘  └───┬────┘
         │               │              │
         └───────────────┼──────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │   Core Services               │
         │  ┌─────────────────────────┐  │
         │  │ Knowledge Graph Engine  │  │
         │  │ • Memory ingestion      │  │
         │  │ • Entity extraction     │  │
         │  │ • Semantic search       │  │
         │  │ • Graph traversal       │  │
         │  └─────────────────────────┘  │
         └───────────────┬───────────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
    ┌──────────┐   ┌───────────┐   ┌─────────┐
    │PostgreSQL│   │  Ollama   │   │  Redis  │
    │+pgvector │   │(Embeddings)│   │(Cache)  │
    └──────────┘   └───────────┘   └─────────┘

🧠 Core Concepts

How It Works: A Temporal Knowledge Graph

SerialMemory goes beyond simple keyword search. It's a semantic memory system that understands meaning and context, tracks how information relates over time, and provides intelligent context retrieval for AI applications.

Memories: The Basic Unit

A memory is any piece of information you store in SerialMemory:

• Natural Language: "John works at Acme Corp in San Francisco on Python projects"
• Structured Data: Notes, facts, observations, conversations, summaries
• Metadata: When it was created, what project it's for, confidence level

Each memory has:

Memory {
  id: "uuid",
  content: "John works at Acme Corp in San Francisco on Python projects",
  embedding: [0.123, -0.456, 0.789, ...],  // 1536-dimensional vector (OpenAI text-embedding-3-small)
  confidence: 0.95,                         // Starts high, decays with time
  layer: L1_CONTEXT,                        // See layers section below
  entities: [
    { type: "PERSON", text: "John" },
    { type: "ORG", text: "Acme Corp" },
    { type: "GPE", text: "San Francisco" },
    { type: "SKILL", text: "Python" }
  ],
  createdAt: "2026-02-11T10:00:00Z",
  lastAccessedAt: "2026-02-11T14:30:00Z"
}

Semantic Search: Understanding Meaning

Instead of keyword matching, memories are found by semantic similarity:

// This query...
"Who works at the tech company in San Francisco?"

// ...finds memories about "John works at Acme Corp in San Francisco"
// Even though keywords don't match exactly!

How it works:

1. Your query is converted to an embedding (1536-dimensional vector)
2. The system finds memories with similar embeddings
3. Results are ranked by meaning, not keywords

This is powered by PostgreSQL's pgvector extension, which uses vector similarity search (KNN) for fast retrieval.

Memory Layers: The Data Lifecycle

Memories are classified into layers based on how processed/refined they are:

Layer	What It Is	Typical Retention	Use Case
L0_RAW	Raw input, minimal processing	30 days	Recently captured notes, conversations
L1_CONTEXT	Contextual understanding, entities extracted	90 days	Processed notes with relationships identified
L2_SUMMARY	Summarized information, themes extracted	180 days	Synthesis of similar concepts
L3_KNOWLEDGE	Extracted knowledge, proven patterns	365 days	Reliable facts, validated learnings
L4_HEURISTIC	Learned patterns, general principles	Indefinite	Core knowledge, fundamental truths

Example Flow:

Raw: "John, Sarah, and Mike met yesterday to discuss the backend API design"
      ↓ (Processing)
L1: Entities extracted - PERSON(John), PERSON(Sarah), PERSON(Mike), 
    Relationships identified - John knows Sarah, John knows Mike
      ↓ (Summarization)
L2: "Key discussion participants coordinated on technical architecture"
      ↓ (Pattern recognition)
L3: "Backend API design is a priority for team coordination"
      ↓ (Generalization)
L4: "The team uses synchronous discussion for architectural decisions"

Memory Confidence Decay: Temporal Forgetting

SerialMemory models human memory: information becomes less reliable over time unless reinforced.

The decay formula:

confidence = initial_confidence × 0.5^(days / half_life)

Default half-life: 90 days

Example:

Day 0:   Confidence = 1.0 (100%)
Day 90:  Confidence = 0.5 (50%)  - Half as confident
Day 180: Confidence = 0.25 (25%) - Quarter as confident
Day 270: Confidence = 0.125 (12.5%)

Why this matters:

• New information is fresh and high-confidence
• Old information without reinforcement becomes less trusted
• Memories below 0.1 (10%) confidence are candidates for archival
• Accessing a memory reinforces it (increases confidence)
• An explicit "reinforce" action can boost confidence

This allows the system to automatically forget unimportant details while keeping validated knowledge intact.

Entity Extraction: Understanding Key Concepts

SerialMemory automatically identifies key entities (named things) in memories:

Type	Examples	Used For
PERSON	John, Sarah, Alice	Finding people-related memories
ORG	Acme Corp, Google, MIT	Finding organization memories
GPE	New York, France, Silicon Valley	Finding location-related context
DATE	2026-02, Next Tuesday, Q1	Finding time-relevant memories
SKILL	Python, React, Leadership	Finding capability-related memories
PROJECT	Project Omega, Dashboard v2	Finding project-specific context

How it works:

1. When a memory is stored, entities are automatically extracted
2. Relationships between entities are identified
3. A knowledge graph is built and maintained

The Knowledge Graph: Building Relationships

SerialMemory doesn't just store memories separately—it builds a knowledge graph of relationships:

John ─────works_at────→ Acme Corp ─────located_in────→ San Francisco
  │                                                          │
  │                                                          │
  └──────knows──────→ Sarah ─────works_at──────→ Acme Corp │
                       │
                       └─────knows──────→ Mike

Projects that use Python:
Dashboard v2 ─────uses────→ Python ─────language_for────→ Backend Systems
Project Omega ─────uses────→ Python

Relationships tracked:

• works_at: Entity1 works at Entity2
• located_in: Entity1 is located in Entity2
• knows: Entity1 knows Entity2
• uses: Entity1 uses Entity2
• created: Entity1 created Entity2
• (And many more, automatically discovered)

Multi-Hop Search: Reasoning Across Context

The real power emerges when traversing multiple hops:

Query: "Find technologies used in projects by people I know"

Search process:

1. Start: Find entities I know (Sarah, Mike, ...)
2. Hop 1: Find projects they work on
3. Hop 2: Find technologies used in those projects
4. Result: [Python, Rust, TypeScript, ...]

Another example:

Question: "Who works with technologies similar to what Mike uses?"

1. Find Mike
2. Find technologies Mike uses
3. Find other people who use similar technologies
4. Return those people

This reveals hidden connections and provides better context
for multi-modal AI reasoning!

Event Sourcing: Complete Audit Trail

Every change to a memory is captured as an immutable event:

MemoryCreated(id, content, timestamp)
MemoryUpdated(id, oldContent, newContent, timestamp)
MemoryReinforced(id, confidence, timestamp)
MemoryDecayed(id, oldConfidence, newConfidence, timestamp)
MemoryArchived(id, reason, timestamp)

Benefits:

• Complete audit trail (GDPR compliant)
• Reproduce system state at any point in time
• Detect tampering or unauthorized changes
• Replay events for debugging

Multi-Tenant Isolation: Security & Privacy

Each tenant's data is completely isolated:

Tenant A                          Tenant B
├── Memories (isolated)           ├── Memories (isolated)
├── Entities                      ├── Entities
├── Relationships                 ├── Relationships
└── Search results (A only)       └── Search results (B only)

Implemented via PostgreSQL Row-Level Security (RLS):

• Database enforces isolation at query time
• Impossible to leak tenant data via SQL
• API keys scoped per tenant
• No cross-tenant search possible

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• .NET 10+ SDK (for development)
• PostgreSQL 15+ (or use Docker)

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/sblanchard/SerialMemoryServer.git
cd SerialMemoryServer

# Start infrastructure (PostgreSQL, Redis, RabbitMQ)
docker compose up -d

# Bootstrap development database
./dev-bootstrap.sh          # Linux/Mac
.\dev-bootstrap.ps1         # Windows

# Run the C# MCP server
dotnet run --project SerialMemory.Mcp

Option 2: Full Stack with Docker

# Start all services
docker compose up --build

# Access dashboard at http://localhost:8080

Services available:

• API: http://localhost:5001
• Dashboard: http://localhost:8080
• PostgreSQL: localhost:5432 (user: postgres)
• Redis: localhost:6379
• RabbitMQ Dashboard: http://localhost:15672 (guest/guest)

Connect to AI Platforms

Claude Desktop (Anthropic)

# Configure in Claude Desktop after starting the server
# See: ./docs/02-quickstart-claude-mcp.md

OpenAI Integration

• Use REST API at http://localhost:5001
• Build custom tools or plugins
• Leverage semantic search and knowledge graph capabilities

📚 Documentation

• Overview & Architecture - Concepts and system design
• Claude Desktop Setup - MCP integration guide
• .NET SDK Guide - C# development
• Node.js SDK Guide - JavaScript/TypeScript
• Data Lifecycle - Memory management and cleanup
• Self-Hosting Guide - VPS deployment
• Local Development - Development environment setup

💻 SDKs & Integrations

Official SDKs

• .NET SDK - Full-featured C# client

  var client = new SerialMemoryClient("http://localhost:5001", "tenant-id", "api-key");
  await client.StoreMemory("My important note", "personal");
  var results = await client.Search("relevant memories", 5);

• Node.js SDK - TypeScript/JavaScript support (coming soon)

MCP Protocol

SerialMemory implements the Model Context Protocol, enabling integration with:

• Claude Desktop (Anthropic)
• OpenAI integrations
• Future compatible AI agents
• Custom MCP clients

🔌 API Endpoints

Memory Management

# Store a memory
POST /api/memories
{
  "content": "I learned about distributed systems",
  "memoryType": "LEARNING",
  "layer": "L0_RAW",
  "metadata": { "subject": "backend" }
}

# Semantic search
POST /api/memories/search
{
  "query": "distributed systems",
  "limit": 5,
  "filters": { "layer": "L0_RAW" }
}

# Get memory by ID
GET /api/memories/{id}

Entity & Knowledge Graph

# List entities
GET /api/entities?limit=100

# Get entity details
GET /api/entities/{entityId}

# Multi-hop graph search
POST /api/graph/search
{
  "startEntity": "John",
  "relationshipType": "knows",
  "hops": 2
}

See OpenAPI Specification for complete API documentation.

📦 Project Structure

SerialMemoryServer/
├── SerialMemory.Mcp/           # C# MCP server (recommended)
├── SerialMemory.Api/           # REST API
├── SerialMemory.Core/          # Domain logic
├── SerialMemory.Infrastructure/# Data access layer
├── SerialMemory.Sdk.DotNet/    # .NET client SDK
├── SerialMemory.ML/            # Embeddings & NLP
├── SerialMemory.Worker/        # Background jobs
├── SerialMemory.Web/           # React dashboard
├── SerialMemory-MCP/           # Standalone MCP server (submodule)
│   └── SerialMemory.Mcp/       # Alternative MCP implementation
├── examples/                   # Ready-to-run examples
├── docs/                       # Documentation
├── docker-compose.yml          # Development stack
└── SerialMemoryServer.sln      # .NET solution file

Submodules

• SerialMemory-MCP - Standalone MCP server for Anthropic & OpenAI
  • Included as a git submodule
  • Can be built and distributed separately
  • Full MCP protocol support for Claude Desktop (Anthropic)
  • Compatible with OpenAI's tool-calling capabilities
  • Ready for future AI agent integrations

Cloning with Submodules

# Clone including submodules
git clone --recurse-submodules https://github.com/sblanchard/SerialMemoryServer.git

# Or if already cloned, initialize submodules
git submodule update --init --recursive

🎓 Examples

AI Second Brain

A persistent "second brain" for Claude to store and retrieve personal notes:

cd examples/ai-second-brain
dotnet run

Features:

• Store notes and learnings
• Semantic search for relevant context
• User persona management
• Automatic entity extraction

Project Context Memory

Per-project memory isolation for development tools:

cd examples/project-context-memory
dotnet run

Features:

• Scoped memory per project/repository
• Metadata-based filtering
• Cross-project search capabilities
• Multi-tenant patterns

See Examples README for more details.

🔐 Security

SerialMemory includes production-ready security features:

Multi-Tenancy

• Complete data isolation with PostgreSQL row-level security (RLS)
• Tenant-scoped API keys
• Secure tenant context propagation

Authentication & Authorization

• JWT token-based API authentication
• Role-based access control (admin, user)
• Service-to-service authentication

Data Protection

• All passwords and secrets in environment variables
• No default credentials in code
• CORS and CSRF protection
• SQL injection protection via parameterized queries

Production Hardening

Use docker-compose.prod.yml for security-hardened deployment:

# Configure environment
cp .env.production.example .env
# Edit .env with strong passwords

# Start with production configuration
docker compose -f docker-compose.prod.yml up -d

See Self-Hosting Guide for detailed security setup.

🛠️ Technology Stack

• Runtime: .NET 10+
• Database: PostgreSQL 15+ with pgvector
• Search: Vector embeddings (1536-dim via OpenAI text-embedding-3-small)
• Caching: Redis
• Queue: RabbitMQ
• NLP: Pattern-based entity extraction (extensible to spaCy, BERT)
• Dashboard: React + TypeScript + Vite
• Protocol: Model Context Protocol (MCP)

📊 Performance

• Supports millions of memories per tenant
• Sub-100ms semantic search queries (with appropriate indexing)
• Horizontal scaling via PostgreSQL connection pooling
• Async processing queue for heavy operations

🧪 Testing

Run the test suite:

# Unit tests
dotnet test SerialMemory.Tests

# MCP integration tests
dotnet test SerialMemory.Mcp.Tests

# All tests with coverage
dotnet test --collect:"XPlat Code Coverage"

📝 Development

Setup Development Environment

# Install dependencies
dotnet restore

# Build solution
dotnet build

# Run with local infrastructure
docker compose up -d
dotnet run --project SerialMemory.Mcp

Code Organization

• SerialMemory.Core: Domain models and business logic
• SerialMemory.Infrastructure: EF Core data access patterns
• SerialMemory.Mcp: MCP server implementation
• SerialMemory.Api: REST API endpoints
• SerialMemory.Tests: Unit and integration tests

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow C# naming conventions (PascalCase for public members)
• Add tests for new features
• Update documentation for API changes
• Ensure all tests pass before submitting PR

📄 License

SerialMemory is released under the MIT License. See LICENSE for details.

🆘 Support & Community

• GitHub Issues: Report bugs and request features
• Documentation: Full docs
• Examples: Ready-to-run examples

🎯 Roadmap

• Python MCP server
• GraphQL API
• Advanced reasoning with multi-hop traversal
• Temporal graph visualization
• Plug-in system for custom entity types
• Multi-language support (embeddings & entity extraction)

🙏 Acknowledgments

SerialMemory is built on these excellent open-source projects:

• PostgreSQL & pgvector
• Ollama for local embeddings
• Model Context Protocol by Anthropic

---

Made with ❤️ for AI-powered applications