Memorykit

🧠 MemoryKit

Enterprise-grade, neuroscience-inspired memory infrastructure for LLM applications

_Because your AI shouldn't have the memory of a goldfish_ 🐠

Quick Start · Documentation · Architecture · API Docs

---

🐠 The Goldfish Problem

Modern LLMs like GPT-4 and Claude have a critical flaw: they're stateless. Every conversation requires reloading the entire context, leading to:

User (Turn 1):   "My name is John, I prefer Python"

AI: "Nice to meet you, John!"

[New session - memory wiped 🧹]

User (Turn 50): "What's my favorite language?" AI: "I don't have that information" ❌

The Cost Problem:

For a typical enterprise chatbot with 100-turn conversations:

MemoryKit solves this. Inspired by how the human brain actually works.

---

🧠 The Neuroscience Solution

Humans don't recall every conversation verbatim. Instead, we use a hierarchical memory system:

The Human Brain Architecture

MemoryKit's Brain-Inspired Architecture

┌──────────────────────────────────────────────────────────────┐

│ PREFRONTAL CONTROLLER │ │ (Executive Function & Planning) │ │ "Which memory layers do I need for this query?" │ └────────────────────┬─────────────────────────────────────────┘ │ ┌────────────┴────────────┐ │ │ ┌────▼─────┐ ┌─────▼──────┐ │ AMYGDALA │ │ HIPPOCAMPUS│ │ Emotion │ │ Indexing │ │ Tagging │ │ │ └────┬─────┘ └─────┬──────┘ │ │ └────────────┬────────────┘ │ ┌───────────────┴────────────────────────────┐ │ │ ┌────▼─────────┐ ┌──────────────┐ ┌───────────────┐ ┌────────────────┐ │ Layer 3 (L3) │ │ Layer 2 (L2) │ │ Layer 1 (L1) │ │ Layer P (LP) │ │──────────────│ │──────────────│ │───────────────│ │────────────────│ │ WORKING │ │ SEMANTIC │ │ EPISODIC │ │ PROCEDURAL │ │ MEMORY │ │ MEMORY │ │ MEMORY │ │ MEMORY │ │ │ │ │ │ │ │ │ │ Redis Cache │ │ Table │ │ Blob + │ │ Pattern │ │ 10 recent │ │ Storage │ │ AI Search │ │ Matching │ │ messages │ │ Facts & │ │ Full convo │ │ Learned │ │ │ │ Entities │ │ history │ │ routines │ │ │ │ │ │ │ │ │ │ < 5ms │ │ ~30ms │ │ ~120ms │ │ ~50ms │ └──────────────┘ └──────────────┘ └───────────────┘ └────────────────┘

Intelligent Query Planning

The Prefrontal Controller decides which layers to query based on intent:

"Continue..."                → L3 only        (500 tokens,  <5ms)

"What's my name?" → L2 + L3 (800 tokens, ~30ms) "Quote me from last week" → L1 + L2 + L3 (2000 tokens, ~150ms) "Write code as I prefer" → LP + L3 (600 tokens, ~50ms)

Result: You only load what you need, when you need it. Just like a human brain.

---

🎯 What Makes MemoryKit Different?

vs. Existing Solutions

Unique Innovations

🧠 First neuroscience-backed memory system for LLMs ⚡ Procedural memory - learns user workflows and preferences 🎯 Importance scoring - Amygdala-inspired emotional tagging 🏗️ Clean Architecture - Enterprise-grade from day one 💰 Highest cost savings - 98-99% reduction vs. naive approaches 🔒 Production-hardened - Security, monitoring, rate limiting built-in

---

🚀 Quick Start

# Clone and build

git clone https://github.com/rapozoantonio/memorykit.git cd memorykit dotnet restore && dotnet build

Run the API

dotnet run --project src/MemoryKit.API

Open Swagger UI

start https://localhost:5001/swagger

Your First Query

// Create conversation

POST /api/v1/conversations { "userId": "user_123", "title": "My Coding Session" }

// Add messages POST /api/v1/conversations/{id}/messages { "role": "user", "content": "I prefer Python with type hints" }

// Later... Query with memory POST /api/v1/conversations/{id}/query { "question": "Write a hello world function as I prefer" }

// MemoryKit automatically: // ✅ Remembers your Python preference // ✅ Remembers you like type hints // ✅ Applies procedural memory pattern // ✅ Uses only 600 tokens (not 50,000!)

👉 See [QUICKSTART.md](docs/QUICKSTART.md) for detailed setup.

---

🏗️ Architecture Highlights

Clean Architecture

┌─────────────────────────────────────────┐

│ API Layer (REST + Controllers) │ └─────────────────┬───────────────────────┘ │ depends on ↓ ┌─────────────────▼───────────────────────┐ │ Application (CQRS + Use Cases) │ └─────────────────┬───────────────────────┘ │ depends on ↓ ┌─────────────────▼───────────────────────┐ │ Domain (Entities + Business Logic) │ ← No Dependencies! └─────────────────▲───────────────────────┘ │ implements ↑ ┌─────────────────┴───────────────────────┐ │ Infrastructure (Azure + Semantic Kernel)│ └─────────────────────────────────────────┘

Memory Consolidation (Sleep-Inspired)

Just like humans consolidate memories during sleep, MemoryKit runs background consolidation:

New Message → Working Memory (L3) → Importance Scoring (Amygdala)

↓ ┌──────────────────┴───────────────────┐ │ │ High Importance? Low Importance? │ │ ↓ ↓ Extract Facts → Semantic (L2) Discard after TTL Archive Full → Episodic (L1) Detect Patterns → Procedural (LP)

---

📊 Performance & Scale

Latency Targets (All Met ✅)

Production Scale

• 10,000+ concurrent conversations
• 1,000+ messages/second
• 500+ queries/second
• Total infrastructure cost: ~$453/month (for 10K users)

---

🎨 Core Features

Memory Operations

✅ Multi-layer storage (Working, Semantic, Episodic, Procedural) ✅ Intelligent query planning (Prefrontal Controller) ✅ Importance scoring (Amygdala Engine) ✅ Automatic fact extraction ✅ Pattern learning and matching ✅ Memory consolidation (background jobs)

Production-Ready

✅ API key authentication ✅ Rate limiting (fixed, sliding, concurrent) ✅ Health checks (live, ready, deep) ✅ Application Insights monitoring ✅ Docker + Docker Compose ✅ Azure Bicep IaC templates ✅ CI/CD with GitHub Actions

Enterprise Features

✅ GDPR-compliant deletion ✅ Multi-tenancy isolation ✅ Comprehensive audit logging ✅ Performance benchmarks (BenchmarkDotNet) ✅ Security hardening (OWASP compliance)

---

📚 Documentation

Getting Started

• [Quick Start](docs/QUICKSTART.md) - 5-minute setup guide
• [Project Status](SECRETS/PROJECT_STATUS.md) - Current state & roadmap
• [Contributing](CONTRIBUTING.md) - How to contribute
• [Changelog](CHANGELOG.md) - Version history

Technical Deep-Dives

• [Architecture](docs/ARCHITECTURE.md) - System design & patterns
• [Cognitive Model](docs/COGNITIVE_MODEL.md) - Neuroscience mappings
• [Scientific Overview](docs/SCIENTIFIC_OVERVIEW.md) - Research background
• [API Reference](docs/API.md) - REST endpoints & SDK
• [Deployment](docs/DEPLOYMENT.md) - Azure production setup
• [Development Guide](DEVELOPMENT_GUIDE.md) - Contributor workflow

---

🔧 Technology Stack

Backend

• .NET 9.0 (C# 13)
• ASP.NET Core Web API
• MediatR (CQRS)
• FluentValidation

Azure Services

• Redis Cache (Working Memory)
• Table Storage (Semantic/Procedural)
• Blob Storage + AI Search (Episodic)
• Azure OpenAI (Embeddings + LLM)

Architecture

• Clean Architecture
• Domain-Driven Design
• SOLID Principles
• Dependency Injection

Testing & Quality

• xUnit (Unit/Integration tests)
• BenchmarkDotNet (Performance)
• Moq (Mocking)
• FluentAssertions

---

🤝 Contributing

We'd love your help making MemoryKit even better!

Quick Start for Contributors

# Fork and clone

git clone https://github.com/YOUR_USERNAME/memorykit.git cd memorykit

Create feature branch

git checkout -b feature/amazing-feature

Make changes

... code code code ...

Run tests

dotnet test

Commit with conventional commits

git commit -m "feat: add amazing feature"

Push and create PR

git push origin feature/amazing-feature

Resources for Contributors

• [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines & code of conduct