Rag.md

Mind Memory Architecture

Overview

The Mind system uses three complementary storage layers:

mind.db ← Source of Truth knowledge.pt ← Portable Export knowledge.faiss ← Vector Search Index

Each component has a specific responsibility.

⸻

Component Responsibilities

1. mind.db

Purpose: Permanent storage of all memory data.

SQLite is the authoritative database and contains the complete memory graph.

Stores • Captures • Events • Concepts • Metadata • Tags • URLs • Related IDs • Lifecycle State • Enrichment Data

Example

{ "id": "capture_123", "title": "SQLite Optimization", "url": "https://example.com", "tags": ["sqlite", "database"], "related_ids": ["capture_456"], "content": "Full article text..." }

Characteristics • Human-readable data • Structured metadata • Editable • Persistent • Source of truth

⸻

2. knowledge.pt

Purpose: Portable snapshot of embeddings and lookup information.

Generated from mind.db.

Stores

{ "version": 1, "embed_model": "BAAI/bge-base-en-v1.5", "count": 1234, "ids": [...], "embeddings": tensor(...) }

Future versions may also contain:

{ "records": [...], "texts": [...], "metadata": [...] }

Characteristics • Fast to load • Portable • Easy to share • Useful for backups • Useful for debugging

Does NOT Replace SQLite

knowledge.pt is an export.

If deleted, it can be regenerated from mind.db.

⸻

3. knowledge.faiss

Purpose: High-speed semantic search.

Generated from embeddings.

Stores

Vector 0 Vector 1 Vector 2 ... Vector N

Characteristics • Extremely fast similarity search • Optimized for vector retrieval • Contains no business data • Contains no content text • Contains no metadata

Does NOT Store • Titles • URLs • Tags • Concepts • Content

It stores vectors only.

⸻

Retrieval Flow

User Query

Example:

How do I convert Gemma models to GGUF?

Step 1

Generate query embedding.

Question ↓ Embedding Model ↓ Query Vector

⸻

Step 2

Search FAISS.

Query Vector ↓ knowledge.faiss ↓ Top Matching Vectors

Example:

Vector 42 Score 0.95 Vector 17 Score 0.88 Vector 88 Score 0.81

⸻

Step 3

Resolve IDs using knowledge.pt.

Vector 42 ↓ knowledge.pt ↓ capture_123

⸻

Step 4

Retrieve full memory.

capture_123 ↓ mind.db ↓ Full Record

Example:

{ "id": "capture_123", "title": "Gemma GGUF Conversion", "content": "Detailed conversion instructions..." }

⸻

Why Three Layers?

SQLite

Best for: • Storage • Metadata • Updates • Relationships

PT

Best for: • Portability • Snapshots • Backup • Debugging

FAISS

Best for: • Semantic Search • Similarity Matching • Fast Retrieval

⸻

Architecture Diagram

                ┌──────────────────┐
                │ User Question    │
                └─────────┬────────┘
                          │
                          ▼
                ┌──────────────────┐
                │ BGE Embedding    │
                └─────────┬────────┘
                          │
                          ▼
                ┌──────────────────┐
                │ knowledge.faiss  │
                │ Vector Search    │
                └─────────┬────────┘
                          │
                          ▼
                ┌──────────────────┐
                │ knowledge.pt     │
                │ Vector → ID Map  │
                └─────────┬────────┘
                          │
                          ▼
                ┌──────────────────┐
                │ mind.db          │
                │ Full Memory Data │
                └──────────────────┘

⸻

Current State

mind.db ✓ Full Memory Storage

knowledge.pt ✓ Embeddings ✓ IDs

knowledge.faiss ✓ Semantic Search

⸻

Future Enhancements

Possible upgrades: • Store metadata inside knowledge.pt • Store content snapshots inside knowledge.pt • Incremental FAISS updates • HNSW FAISS indexes for larger datasets • Hybrid keyword + vector search • Multi-model embedding support • Automatic synchronization between SQLite and exports

⸻

Summary

The architecture separates responsibilities: • mind.db stores the memories. • knowledge.faiss finds similar memories. • knowledge.pt maps vectors back to memory IDs.

This design keeps storage, retrieval, and search independent while allowing fast semantic memory lookup at scale. :::

This document should give future contributors a clear understanding of why all three files exist and how they work together.