> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MemU Architecture

> Inside MemU — PostgreSQL + pgvector, hybrid search, auto-capture, significance scoring, and embeddings.

## Overview

<Tooltip tip="Memory Unit — ArgentOS's built-in persistent memory system.">MemU</Tooltip> (Memory Unit) is ArgentOS's built-in persistent memory system. It supports two backends:

* **PostgreSQL 17 + pgvector** (recommended) — concurrent access, shared knowledge, HNSW vector indexes, tsvector full-text search with GIN indexes
* **SQLite** (fallback) — single-process, local-only, FTS5 full-text search, stored at `~/.argentos/memory.db`

The installer sets up PostgreSQL by default. SQLite is available as a zero-dependency fallback for simpler setups.

## Database Schema

The core memory table contains:

| Column              | Type    | Description                                            |
| ------------------- | ------- | ------------------------------------------------------ |
| `id`                | INTEGER | Primary key                                            |
| `content`           | TEXT    | The memory content                                     |
| `type`              | TEXT    | Category (fact, preference, event, relationship, etc.) |
| `significance`      | INTEGER | Importance score (1-10)                                |
| `entities`          | TEXT    | JSON array of referenced entities                      |
| `emotional_context` | TEXT    | Emotional tone or context                              |
| `source`            | TEXT    | Where this memory came from                            |
| `created_at`        | TEXT    | Timestamp of creation                                  |
| `updated_at`        | TEXT    | Last update timestamp                                  |
| `embedding`         | BLOB    | Vector embedding for semantic search                   |

## Full-Text Search

MemU uses different full-text search engines depending on the backend:

**PostgreSQL** (default): `tsvector` with GIN indexes — supports ranked search, stemming, language-aware tokenization, and phrase matching.

**SQLite** (fallback): FTS5 extension — boolean queries, phrase matching, prefix matching.

Both backends support:

* **Boolean queries**: `preference AND open-source`
* **Phrase matching**: `"infrastructure specs"`
* **Prefix matching**: `config*`
* **OR queries**: `telegram OR discord`

### Search Tips

<Tip>
  * Single keywords work best for broad recall
  * Use OR for multi-word queries to improve recall
  * Strip common stop words for better results
  * PostgreSQL handles stemming and language-aware tokenization automatically
</Tip>

## Significance Scoring

Every memory has a significance score from 1-10:

| Score | Level     | Example                                      |
| ----- | --------- | -------------------------------------------- |
| 1-2   | Low       | Passing observations                         |
| 3-4   | Medium    | Useful context                               |
| 5-6   | High      | Important facts and preferences              |
| 7-8   | Very High | Key personal information, critical decisions |
| 9-10  | Critical  | Core identity, security-sensitive data       |

<Info>
  Higher significance memories are prioritized in search results and bootstrap injection.
</Info>

## Auto-Capture

The agent is trained to automatically store important information without being explicitly asked. When it detects a new fact, preference, event, or relationship in conversation, it calls `memory_store` proactively.

## Embeddings

MemU supports vector embeddings for semantic similarity search. Embeddings are generated when memories are stored and used alongside full-text search for hybrid ranking.

**PostgreSQL**: pgvector with HNSW indexes for fast approximate nearest neighbor search.

**SQLite**: sqlite-vec extension for local vector search.

```
Final Score = text_relevance * weight + embedding_similarity * weight + significance_boost
```

## Storage

**PostgreSQL** (default):

```
postgres://localhost:5433/argentos    # Database with pgvector extension
Redis on port 6380                    # Agent state, presence, pub/sub
```

**SQLite** (fallback):

```
~/.argentos/memory.db      # Main database
~/.argentos/memory.db-wal  # Write-ahead log
~/.argentos/memory.db-shm  # Shared memory
```

The database is accessed via `getMemuStore()` in `src/memory/memu-store.ts`.