SynapseMemory 

The Ultimate Local-First Agentic Memory Framework for Apple Silicon.

Uniting the best architectural innovations of Mem0, Supermemory, Letta/MemGPT, and Zep into a unified, lightweight native Swift library. 100% on-device execution with zero cloud hosting costs, seamlessly synced across user Apple devices via Apple CloudKit private database.

---

⚡ 30-Second Quick Start

import SynapseMemory

// 1. Initialize SynapseClient (Defaults to Apple Foundation Models + CloudKit Sync)
let synapse = try await SynapseClient(config: SynapseConfig())

// 2. Add conversational turns (Extracts memories, knowledge graph triples & recall logs)
let messages = [
    Message(role: .user, content: "Hi! I am Alex, I live in Bangkok, and I build native Swift apps."),
    Message(role: .assistant, content: "Great to meet you Alex! I will remember you live in Bangkok.")
]
try await synapse.add(messages: messages, userId: "alex_123")

// 3. Ingest documents and web bookmarks with auto-tagging (Supermemory feature)
try await synapse.ingest(
    content: "Apple Intelligence combines generative models with on-device personal context...",
    title: "Apple Intelligence Notes",
    userId: "alex_123",
    tags: ["apple", "ai", "privacy"]
)

// 4. Hybrid Search (Accelerate SIMD + SQLite FTS5 + Time-Decay)
let results = try await synapse.search(query: "Where does Alex live?", userId: "alex_123")
for item in results {
    print("Found Memory: \(item.item.memory) (Score: \(item.score))")
}

// 5. Query Knowledge Graph Triples (Mem0 & Graphiti feature)
let triples = try await synapse.getRelations(userId: "alex_123")
// Prints: Alex -> [lives_in] -> Bangkok

// 6. RAG — Ingest a file and retrieve LLM-ready context with citations
let pdfURL = Bundle.main.url(forResource: "Q3Report", withExtension: "pdf")!
let chunks = try await synapse.ingestDocument(fileURL: pdfURL, tags: ["finance", "Q3"])

let ragContext = try await synapse.retrieveContext(query: "What was the revenue growth?", limit: 4)
print(ragContext.contextPrompt)   // Ready-to-paste LLM prompt with [1][2] citations
print(ragContext.bibliography())  // [1] "Q3Report.pdf" - Revenue Section, Page 4

---

📊 Open-Source Competitor Comparison

Why pay recurring server bills or manage Docker containers when Apple Silicon can run everything on-device for free?

Capability / Architecture Dimension	SynapseMemory 	Mem0 (Cloud / OSS)	Supermemory	Letta (MemGPT)	Zep
Zero Hosting Cost ($0.00 / Zero Server Bills)	✅ Yes ($0.00)	❌ Paid / Docker	⚠️ Paid Cloud	⚠️ Self-Hosted	❌ Subscription
100% On-Device Local Privacy	✅ Complete	⚠️ Python / Cloud	❌ Cloud Only	⚠️ Local Python	❌ Cloud Only
Hardware-Accelerated SIMD Vector Search	✅ Apple Accelerate (vDSP)	❌ Qdrant / Chroma	❌ Cloud Index	❌ Postgres / Chroma	❌ Cloud Index
Full-Text BM25 Keyword Search	✅ SQLite FTS5 Virtual Tables	⚠️ SQLite / Postgres	⚠️ Keyword Search	⚠️ SQL Search	⚠️ Hybrid Cloud
Hybrid Search Fusion (Dense + Sparse + Decay)	✅ Vector + BM25 + Time Decay	⚠️ Hybrid RRF	❌ Vector Only	❌ Vector Only	⚠️ Hybrid Cloud
Knowledge Graph Memory (Entity Triples)	✅ Local SQLite Triples	✅ Graphiti / NetworkX	❌ Not Supported	⚠️ Structured Tools	✅ Temporal Graphiti
Bi-Temporal Fact Superseding (validFrom/validTo)	✅ Built-in	✅ Built-in	❌ Not Supported	❌ Not Supported	⚠️ Temporal Logs
Document & Bookmark Ingestion (Chunk & Auto-Tag)	✅ Built-in (ingest())	⚠️ Custom Loaders	✅ Built-in	⚠️ Attachments	❌ Not Supported
Hierarchical Working Memory Blocks (Persona State)	✅ Built-in (coreBlock)	❌ Not Supported	❌ Not Supported	✅ Core Architecture	❌ Not Supported
Chronological Recall Memory Log & Playback	✅ Built-in (recall())	❌ Not Supported	❌ Not Supported	✅ Built-in	⚠️ Dialog Log
Rolling Dialogue Summarization & Context Compression	✅ Built-in (summarize())	❌ Not Supported	❌ Not Supported	⚠️ Tool Calls	✅ Core Architecture
Multi-Device Private Sync (Zero Third-Party DB)	✅ Apple CloudKit iCloud	❌ Cloud DB Cluster	⚠️ Web Sync	❌ Server Sync	❌ Cloud Backend
On-Device Apple Foundation Models & Guided Generation	✅ Native Zero-Config	❌ Cloud API / Ollama	❌ Cloud API	❌ Cloud API / Ollama	❌ Cloud API
Local Offline LLM Support (Ollama on Mac)	✅ Built-in (OllamaProvider)	⚠️ Local Python	❌ Cloud Only	⚠️ Local vLLM	❌ Cloud Only
Apple Native Ecosystem (CoreSpotlight & Siri AppIntents)	✅ Native iOS/macOS	❌ Not Supported	❌ Not Supported	❌ Not Supported	❌ Not Supported
Multi-Format RAG Document Loaders (PDF, MD, Code, CSV, JSON)	✅ Built-in (6 loaders)	❌ Not Supported	❌ Not Supported	❌ Not Supported	❌ Not Supported
Recursive & Syntax-Aware Chunking Strategies	✅ 3 built-in strategies	❌ Not Supported	❌ Not Supported	❌ Not Supported	❌ Not Supported
On-Device Vision OCR (Apple Vision Framework)	✅ Zero-cost on-device	❌ Not Supported	❌ Not Supported	❌ Not Supported	❌ Not Supported
Citation Tracking & RAG Context with Numbered References	✅ Built-in RAGContextBuilder	❌ Not Supported	❌ Not Supported	❌ Not Supported	❌ Not Supported

For a detailed architectural deep dive, see Competitor Comparison & Analysis.

---

📚 Granular Documentation Catalog (docs/)

Explore complete, granular documentation inside the docs/ directory:

Section	Topic & Documentation Link	Description
🚀 Getting Started	Quick Start Guide	Installation via SPM, requirements, and basic usage.
	Configuration Reference	SynapseConfig options, vector dimensions, and storage settings.
🏛️ Architecture	System Architecture	Multi-tiered memory engine, actor isolation, and subsystem design.
	Competitor Matrix	Architectural comparison vs Mem0, Supermemory, Letta, and Zep.
📖 Guides	Agent & LLM Integration	Standard OpenAPI/JSON schema tools for SynapseAgent & Foundation Models.
	Conversational Memory	State machine (ADD, UPDATE, DELETE), bi-temporal fact superseding.
	Knowledge Graph	Entity triple extraction, SQLite graph store, and graph traversal.
	Document & RAG Ingestion	PDF, Markdown, Code, CSV/JSON loaders; RecursiveCharacter/Code/PDF chunkers; Vision OCR; ingest() & ingestDocument().
	RAG Pipeline Architecture	Full pipeline: Loaders → Chunkers → KnowledgeBaseIndex → RAGRetriever → RAGContext with citations & bibliography.
	Hybrid Search Engine	Fusion of SIMD vector search (vDSP), SQLite FTS5 BM25, and time-decay.
	CloudKit Private Sync	Encrypted multi-device sync, delta change tokens, and offline queues.
	Apple Integrations	Spotlight system indexing, Siri AppIntents, and BGTaskScheduler.
🛈 API Reference	SynapseClient API	Complete Swift API reference for SynapseClient actor methods, including RAG APIs.
	Intelligence Providers	Apple Foundation Models, Ollama, OpenAI, and Mock providers.

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                       Apple Intelligence Client App                         │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                             SynapseClient (Actor)                           │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Apple Foundation     │ │ SIMD Vector          │ │ Knowledge Graph      │ │
│ │ Model Extractor      │ │ Search Engine        │ │ Engine (Triples)     │ │
│ ├──────────────────────┤ ├──────────────────────┤ ├──────────────────────┤ │
│ │ Supermemory Ingest   │ │ Letta Hierarchical   │ │ Zep Rolling Dialogue │ │
│ │ & Document Chunker   │ │ Recall Memory Log    │ │ Summarizer Engine    │ │
│ └──────────┬───────────┘ └──────────┬───────────┘ └──────────┬───────────┘ │
└────────────┼────────────────────────┼────────────────────────┼──────────────┘
             │                        │                        │
┌────────────▼────────────────────────▼────────────────────────▼──────────────┐
│                           Core Storage Subsystem                            │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Local Hybrid SQLite FTS5 + Accelerate SIMD Vector Store + Graph Store   │ │
│ └────────────────────────────────────┬────────────────────────────────────┘ │
└──────────────────────────────────────┼──────────────────────────────────────┘
                                       │ CloudKit Delta Sync
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                    Apple CloudKit Private iCloud Database                   │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CKRecordZone: "SynapsePrivateZone"                                      │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

---

🏛️ Open-Source Attribution & Inspiration

• Mem0: State machine & bi-temporal fact invalidation.
• Supermemory: Document chunking & tag extraction.
• Letta / MemGPT: Tiered working memory & recall logs.
• Zep: Rolling dialogue summarization & recency decay.

---

⚖️ License

SynapseMemory is licensed under the MIT License.