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.