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

# How Memory Works

> Embeddings, vector search, similarity scoring, and importance weighting.

## From text to vectors

When you store a memory, MemoClaw converts the text into a **512-dimensional vector** using OpenAI's `text-embedding-3-small` model. These vectors capture semantic meaning — similar concepts produce similar vectors, even with different wording.

For example, "user prefers dark mode" and "they like dark themes" will have vectors that are very close together, even though the words are completely different.

## Vector similarity search

When you recall, your query is also converted to a vector. PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) finds the closest stored vectors using **cosine distance**. The HNSW (Hierarchical Navigable Small World) index makes this fast even with millions of memories.

## Scoring formula

<Info>
  **Hybrid recall scoring (4-signal approach):**

  ```
  hybrid = vector_sim × 0.55 + keyword_match × 0.25 + recency × 0.20
  score  = hybrid × context_importance × access_boost × type_decay
  ```

  Signals:

  * **vector\_sim**: Cosine similarity (0–1) — primary semantic signal
  * **keyword\_match**: Full-text/BM25 match, normalized (0–1) — exact term matches
  * **recency**: `exp(-age_days / 30)` — temporal freshness
  * **context\_importance**: Importance dynamically boosted by query relevance
  * **access\_boost**: `min(1 + access_count × 0.1, 2.0)` — frequently recalled memories rank higher
  * **type\_decay**: Exponential decay based on memory type half-life (correction: 180d, preference: 180d, decision: 90d, project: 30d, observation: 14d, general: 60d). Pinned memories are exempt from decay. Memories with more relations decay slower.

  When keyword match is strong (>0.3), its weight increases to 0.35 (vector drops to 0.45) for adaptive boosting.
</Info>

This means highly important memories surface first when similarity is close, but a low-importance memory with high semantic relevance can still beat a high-importance memory with weak relevance.

## Embedding cache

MemoClaw maintains an **LRU cache of 1,000 embeddings**. Repeated text won't consume additional OpenAI API tokens. Cache hits are instant.

This is particularly useful for agents that recall the same queries across sessions — the embedding is computed once and reused.

## Namespaces

Use namespaces to isolate memories per project or context. The default namespace is `"default"`.

**Suggested strategy:**

| Namespace pattern | Use case                          |
| ----------------- | --------------------------------- |
| `default`         | General user info and preferences |
| `project-{name}`  | Project-specific knowledge        |
| `session-{date}`  | Session summaries                 |

Namespaces are scoped per user — two different wallets can each have a `default` namespace without any overlap.

## Tags and metadata filtering

Attach **tags** to memories for category-based filtering. Recall supports filtering by tags (match any) and by date (`after`).

Metadata is stored as JSONB and supports:

* Up to **20 keys** per memory
* Up to **3 levels** of nesting
* Any JSON-compatible values

```json theme={null}
{
  "tags": ["preference", "editor"],
  "source": "onboarding",
  "context": {
    "project": "memoclaw",
    "session": "2025-01-15"
  }
}
```

## When to store

<Tip>
  **Good candidates for storage:**

  * User preferences and settings
  * Important decisions and rationale
  * Context useful in future sessions
  * Project-specific knowledge
  * Lessons learned from corrections
</Tip>

## When NOT to store

<Warning>
  **Avoid storing:**

  * Passwords, API keys, tokens, or secrets
  * Ephemeral back-and-forth conversation
  * Information already stored (recall first to check)
  * Raw data dumps (summarize first)
</Warning>

## Best practices

1. **Be specific** — "Ana prefers VSCode with vim bindings" beats "user likes editors"
2. **Add metadata** — Tags enable filtered recall later
3. **Set importance** — 0.9+ for critical info, 0.5 for nice-to-have
4. **Use namespaces** — Isolate memories per project
5. **Don't duplicate** — Recall before storing similar content
6. **Respect privacy** — Never store secrets