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

# Memory System

> Persistent memory across sessions with semantic search and graph edges

TENET's memory system ensures nothing is forgotten between sessions. Every journal entry, code change, and decision is indexed, embedded, and searchable.

## What Gets Remembered

| Source              | What's Indexed                                    | How Often        |
| ------------------- | ------------------------------------------------- | ---------------- |
| **Journal entries** | Features, fixes, decisions, discoveries, pivots   | Every 60 seconds |
| **Code headers**    | `@purpose` annotations from source files          | Every 5 minutes  |
| **Manual memories** | Insights, notes, decisions via `tenet_memory_add` | On demand        |

## How Search Works

TENET uses hybrid search — combining lexical and semantic approaches for best results:

```
Query: "CLI startup optimization"
         |
    +----+----+
    |         |
  BM25+    Embedding
  (lexical) (semantic)
    |         |
    +----+----+
         |
   Reciprocal Rank
      Fusion (RRF)
         |
    Ranked Results
```

### BM25+ (Always Available)

Term-frequency scoring with:

* Stopword removal and phrase detection
* Adaptive document length normalization
* Query term weighting based on IDF
* Positive IDF floor (BM25+ variant) — common terms still contribute

### Semantic Search (When Embeddings Available)

Cosine similarity on `text-embedding-3-small` vectors:

* 1536 dimensions
* OpenAI or OpenRouter fallback
* Auto-backfill: if key was missing when indexed, embeddings are added later

### Reciprocal Rank Fusion

Merges BM25 and embedding results by rank position, not raw scores. More robust than linear interpolation because it doesn't require score normalization.

## Current Stats

```bash theme={null}
tenet memory status
```

```
total_memories: 349
by_type: {feature: 96, milestone: 96, decision: 55, fix: 40, ...}
embeddings: {available: true, count: 349, model: "openrouter/text-embedding-3-small"}
```

**349/349 memories embedded** — zero gaps.

## Graph Edges

Memories aren't isolated. They connect to each other:

| Edge Type     | Meaning                     | Example                                                         |
| ------------- | --------------------------- | --------------------------------------------------------------- |
| `updates`     | New info supersedes old     | "CLI speed now 98ms" updates "CLI speed was 6.7s"               |
| `contradicts` | New finding invalidates old | "Connection pooling helps" contradicts "Keep connections short" |
| `related_to`  | Topically connected         | Memory about eval system → related to agent config              |
| `caused_by`   | Causal relationship         | "Test failures" caused\_by "Dependency upgrade"                 |
| `part_of`     | Hierarchical grouping       | Session memories → part\_of project milestone                   |

```bash theme={null}
# Add a link via API
curl -X POST http://localhost:4360/api/memory/link \
  -H "Content-Type: application/json" \
  -d '{"from": 42, "to": 17, "type": "updates"}'
```

## Code Header Indexing

Files with `@purpose` annotations are automatically indexed:

```typescript theme={null}
/**
 * Memory Indexer Module
 *
 * @purpose Automatic indexing of journal entries and code headers
 */
```

This creates a searchable memory entry:

* Source: `file`
* Type: `code-header`
* Content: `src/lib/memory-indexer.ts: Automatic indexing of journal entries and code headers`

Scans: `src/`, `packages/`, `scripts/`, `eval/`
Updates if `@purpose` changes. Deduped by file path.

## Knowledge Doc Lifecycle

Knowledge docs (VISION.md, THESIS.md, etc.) are audited for staleness:

```bash theme={null}
tenet organize
```

```
  Doc Health

  ✓  VISION              0d old  drift:   20%  mentions: 221
  ✓  THESIS              0d old  drift:   20%  mentions: 223
  ✓  NARRATIVE            0d old  drift:   20%  mentions: 206

  0 of 5 docs need attention
```

When docs drift from journal evidence, `tenet organize` generates a `PENDING.md` with proposed updates and open questions for human review.

<CardGroup cols={2}>
  <Card title="Search" icon="magnifying-glass" href="/memory/search">
    BM25+ hybrid search internals and query optimization.
  </Card>

  <Card title="Graph Edges" icon="diagram-project" href="/memory/graph-edges">
    Structured relationships between memories.
  </Card>

  <Card title="Embeddings" icon="microchip" href="/memory/embeddings">
    Auto-backfill, model selection, and fallback behavior.
  </Card>

  <Card title="Code Headers" icon="code" href="/memory/code-headers">
    Indexing @purpose annotations from source files.
  </Card>
</CardGroup>