> ## 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.

# Journal System

> Append-only event log that captures everything

The journal is the source of truth for everything that happens in a TENET project. Every feature, fix, decision, and discovery is captured as a JSONL entry.

## Format

Each journal file is JSONL (one JSON object per line):

```json theme={null}
{
  "v": 2,
  "ts": "2026-03-22T21:30:00.000Z",
  "session": "session-goose-20260322-2009-4dfeec",
  "type": "feature",
  "status": "complete",
  "title": "Memory system — auto-backfill embeddings",
  "summary": "Periodic indexer now auto-backfills missing embeddings on first tick",
  "detail": "Fixed root cause: one 35K-char memory was killing the entire backfill loop",
  "files": ["src/lib/memory-indexer.ts", "src/lib/memory-search.ts"],
  "learned": ["Truncate content >28K chars for embedding models"],
  "next": "Add graph edges to memory schema"
}
```

## Entry Types

| Type          | When to Use                                                                                                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `feature`     | New capability shipped                                                                                                                                                                              |
| `fix`         | Bug fix                                                                                                                                                                                             |
| `decision`    | Architectural or strategic choice                                                                                                                                                                   |
| `discovery`   | Something learned or found                                                                                                                                                                          |
| `insight`     | Pattern recognized or understanding crystallized                                                                                                                                                    |
| `teacup`      | The specific concrete moment *before* an insight — the door back to understanding, not the conclusion. Write what you were looking at: the file, the line, the exact detail that triggered clarity. |
| `milestone`   | Significant achievement                                                                                                                                                                             |
| `note`        | General observation or context                                                                                                                                                                      |
| `pivot`       | Context checkpoint (mid-session save)                                                                                                                                                               |
| `session-end` | Session completed                                                                                                                                                                                   |

## File Location

```
.tenet/journal/
├── main.jsonl                              # Main branch entries
├── session-goose-20260322-2009-4dfeec.jsonl  # Session-specific
└── flow-engine.jsonl                       # Automated flow entries
```

## Reading Journals

```bash theme={null}
# Recent work summary
tenet synopsis 24

# Search memory (journals are indexed into memory DB)
tenet ask "What did we do about embeddings?"

# Raw journal
tail -5 .tenet/journal/main.jsonl | python3 -m json.tool
```

## How Journals Feed the System

```
Journal entry written
  ↓ (every 60 seconds)
Memory indexer reads it
  ↓
Extracts content (title + summary + detail + files + learned)
  ↓
Computes TF-IDF tokens
  ↓
Computes embedding (text-embedding-3-small)
  ↓
Stored in memory.db → searchable via tenet_memory_search
  ↓
Training tuples mined → feeds policy head
```

## Writing Journal Entries

Agents write journal entries automatically via the Pi extension. You can also write them manually:

```bash theme={null}
# Via the memory tool
tenet_memory_add --title "My discovery" --content "Details..." --type discovery

# Directly to JSONL
echo '{"v":2,"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","session":"main","type":"note","title":"My note","summary":"Details"}' >> .tenet/journal/main.jsonl
```