MagiCore 1.0.0

<div align="center"> <img src="assets/readme-header.svg" alt="MagiCore semantic, temporal, and spatial memory systems online" width="100%" /> </div>

<h1 align="center">MagiCore</h1>

<p align="center"><strong>Long-term memory infrastructure for AI applications and agents in .NET.</strong></p>

<p align="center"> Store what happened. Recover what mattered. Recall it in the right context. </p>

<div align="center">

</div>

MagiCore is a local-first C# library for building memory into agents, assistants, simulations, and robots. It combines semantic retrieval with auditable history, event-time recall, cognitive consolidation, and provider-neutral persistence.

Everything runs in-process by default with no telemetry and no required hosted service. Production integrations use standard Microsoft.Extensions.AI and Microsoft.Extensions.VectorData abstractions, so model and storage choices stay at the application boundary.

Start the core

Install the package:

dotnet add package MagiCore

Then create a zero-configuration memory service. The default store, extractor, and lexical embedding generator are deterministic and local:

using MagiCore;

var memory = new MemoryService();
await memory.AddAsync("I prefer C# over Python.", new MemoryAddOptions { UserId = "alice" });
var results = await memory.SearchAsync(
    "What language does Alice like?",
    new MemorySearchOptions { Filter = new MemoryFilter(UserId: "alice"), TopK = 1 });

Console.WriteLine(results[0].Memory.Text);

How memory moves

flowchart LR
    subgraph Ingestion["01 / Ingest"]
        Msg["User & Agent Messages"] --> Extractor["LLM / Lexical Extractor"]
        Extractor --> Dedupe["Deduplication & Conflict Resolver"]
    end

    subgraph Behaviors["02 / Resolve and shape"]
        Dedupe --> Normal["Normal Fact Memory"]
        Dedupe --> Dream["Dreaming & Consolidation"]
        Dedupe --> Assoc["Spontaneous Associations"]
        Dedupe --> Identity["Personality / First-Person"]
    end

    subgraph Storage["03 / Persist"]
        Normal & Dream & Assoc & Identity --> Store["Storage Engine<br/>(InMemory / Qdrant / Microsoft.Extensions.VectorData)"]
    end

    subgraph Retrieval["04 / Recall"]
        Query["Search Query"] --> Hybrid["Hybrid Search<br/>(Dense Vector + BM25)"]
        Store --> Hybrid
        Hybrid --> Rerank["Reranker (Cohere / Cross-Encoder / LLM)"]
        Rerank --> Context["Filtered Agent Context"]
    end

System capabilities

• Semantic & Hybrid Retrieval: Dense vector search combined with BM25 keyword scoring and LLM/Cohere/Cross-Encoder reranking.
• Multimodal & Image Memory: Ingest image content through Microsoft.Extensions.AI and search direct image embeddings with IImageEmbeddingGenerator.
• Model Integration: Bring any compatible IChatClient and IEmbeddingGenerator; examples cover OpenAI, Ollama, and local ONNX workflows.
• Cognitive Behaviors:
  • Normal: Standard factual extraction and recall.
  • Dreaming: Background memory consolidation, compressing repeated facts into long-term insights.
  • Random Thoughts: Spontaneous associations and creative prompt injections.
  • Personal/Identity: First-person perspective memory shaping.
• Audit, Temporal Reads & Recovery: Track ADD, UPDATE, and DELETE events, query historical state without mutation, and perform filtered rollback with history-capable stores. See Providers & Persistence for provider limitations.
• 3D Spatial & Robotics Memory: Save map-scoped observations, reconstruct event-time object beliefs with uncertainty and visibility states, derive conservative metric relations, and recall controller-reported action episodes.
• Scoped Organization: User, session, and agent-level memory partitioning with run filters and metadata matching.
• Model Context Protocol (MCP): A runnable sample server exposes nine local memory tools through the official .NET MCP SDK.
• Batch Operations: High-throughput transactional batch embeddings and searches.

Build from local to durable

Local memory lifecycle

using MagiCore;

var memory = new MemoryService();

// Add a memory
await memory.AddAsync("I prefer dark mode and vim keybindings", userId: "alice");

// Search memories
var results = await memory.SearchAsync(
    "What editor settings does Alice prefer?",
    new MemoryFilter(UserId: "alice"),
    topK: 3);

foreach (var result in results)
{
    Console.WriteLine($"{result.Score:F3}: {result.Memory.Text}");
}

// Update and History
var allMemories = await memory.GetAllAsync(new MemoryFilter(UserId: "alice"));
var memoryId = allMemories[0].Id;
await memory.UpdateAsync(memoryId, "I prefer dark mode and Neovim keybindings");
var history = await memory.GetHistoryAsync(memoryId);

Multi-turn and multimodal extraction

// Extract facts from messages including images
await memory.AddAsync(
[
    new Message("user", "Here is my conference receipt."),
    Message.FromImage(receiptBytes, "image/png"),
    new Message("assistant", "I've reviewed the receipt.")
],
userId: "alice",
scope: MemoryScope.User);

Durable vector storage

using MagiCore;
using Microsoft.Extensions.VectorData;

// Use any MEVD-compatible vector store (Azure AI Search, PostgreSQL/pgvector, SQLite, Redis, Qdrant, Milvus, Pinecone, etc.)
VectorStore vectorStore = GetVectorStore();
var store = new VectorDataMemoryStore(vectorStore, new VectorDataMemoryStoreOptions
{
    CollectionName = "user_memories",
    VectorDimensions = 384,
    AutoCreateCollection = true
});
await store.InitializeAsync();

var memory = new MemoryService(store: store);

Choose a working sample

Each sample is runnable and focused on one deployment path. Start with Getting Started, then select the infrastructure your application needs.

• Getting Started: Zero-setup CRUD, search, and history tracking.
• SQLite Vector Store: Local embedded persistence with Microsoft.Extensions.VectorData and sqlite-vec.
• PostgreSQL pgvector: Enterprise persistent vector storage with Microsoft.Extensions.VectorData and pgvector.
• Memory Behaviors: Fact extraction, dreaming/consolidation, spontaneous associations, and personality-shaped memory.
• 3D Spatial Memory Robot: A Godot warehouse robot that remembers camera observations and recalls nearby objects from PostgreSQL/pgvector.
• Ollama Integration: Fully offline local LLM extraction and embeddings.
• Agent Framework Memory: Cross-session persistent memory with Microsoft.Extensions.VectorData for Microsoft Agent Framework.
• MCP Server: Standalone Model Context Protocol host for Claude Desktop, Cursor, and other MCP clients.

Operator manual

• Guides: Documentation Home | Getting Started | Providers & Persistence
• Reference: API Reference
• Benchmarking: Evaluation Harness & Metrics
• Architecture: Architecture Overview | Contribution Guidelines

Verify the system

dotnet build .\MagiCore.slnx
dotnet test .\tests\MagiCore.Tests\MagiCore.Tests.csproj

License

MagiCore is licensed under the Apache License 2.0.