Architecture Overview

Magneteco is a multi-tenant memory service designed to provide persistent, domain-aware memory for AI agents across multiple applications. It combines vector similarity search with knowledge graphs to enable both semantic retrieval and precise relationship queries.

Design Principles

Memory is infrastructure, not a feature — Build once, use everywhere
Domain-aware extraction — Each app teaches the system what matters
Events, not just conversations — Memory comes from system events too
Temporal awareness — Recent information is weighted higher
Conflict resolution — New facts supersede old, with audit trail
Graceful degradation — System works even if graph is unavailable

System Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                                 CLIENTS                                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                          │
│  │  App A  │  │  App B  │  │  App C  │  │ Webhook │                          │
│  │ (Agent) │  │ (Agent) │  │ (Agent) │  │ Sources │                          │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                          │
└───────┼────────────┼────────────┼────────────┼───────────────────────────────┘
        │            │            │            │
        └────────────┴─────┬──────┴────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                            API GATEWAY                                        │
│                                                                              │
│  POST /memorize      POST /events      POST /webhooks/:source                │
│  POST /retrieve      GET  /context     POST /forget                          │
│  GET  /categories    GET  /entities    GET  /health                          │
└──────────────────────────────────────────────────────────────────────────────┘

Data Layer

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   PostgreSQL    │  │     Neo4j       │  │       S3        │
│   + pgvector    │  │    (Graph)      │  │  (Raw Logs)     │
│                 │  │                 │  │                 │
│  • items        │  │  • Entities     │  │  • Immutable    │
│  • categories   │  │  • Relations    │  │  • Versioned    │
│  • checkpoints  │  │  • Mentions     │  │  • Timestamped  │
│  • resources    │  │                 │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘