Core Concepts
Tenax organizes knowledge into five distinct types, each serving a specific purpose in maintaining project continuity.
Knowledge Types
Architecture & Technology Choices
Decisions capture architecture choices, technology selections, and design approaches. They answer "what did we choose and why?"
| Field | Description |
|---|---|
topic | Category (e.g., "database", "auth", "api") |
decision | What was decided |
rationale | Why this choice was made |
Example: "Using PostgreSQL for relational data" with rationale "Team has expertise, strong ACID compliance"
Coding Conventions & Best Practices
Patterns capture coding conventions, architectural patterns, and established best practices for the project.
| Field | Description |
|---|---|
name | Pattern identifier (e.g., "error-handler") |
description | What the pattern does |
usage | When to apply this pattern |
Example: "error-boundary" - Wrap async route handlers in try-catch with standardized error response
Work Items & TODOs
Tasks track work items, pending todos, and follow-up actions that emerge during development.
| Field | Description |
|---|---|
title | Task description |
status | pending, in-progress, completed, cancelled |
priority | low, medium, high, critical |
Example: "Add unit tests for authentication module" - high priority, pending
Discoveries & Learnings
Insights capture discoveries, learnings, gotchas, and important observations that don't fit other categories.
| Field | Description |
|---|---|
content | The insight or observation |
context | Optional context about when this applies |
Example: "Rate limiting is per-user, not per-app, which affects our caching strategy"
Complete Conversation Snapshots
Sessions are complete conversation snapshots with metadata. They contain the raw transcript and extracted knowledge.
| Field | Description |
|---|---|
id | Session identifier (e.g., "001") |
summary | Brief description of conversation |
tokenCount | Tokens in session |
filesModified | Files changed during session |
How Knowledge Flows
Knowledge flows through the system in three stages:
Capture
During your session, hooks track file changes. When the session ends (or auto-compacts), the full transcript is saved.
Extract
The extractor scans for compact markers ([D], [P], [T], [I]) and uses heuristics to identify knowledge. Quality scoring filters noise.
Index
Extracted knowledge is embedded using a local ML model and stored in a vector database for semantic search.
Proactive History Checking
When you discuss architecture, libraries, or patterns, Claude automatically searches Tenax first. This surfaces existing decisions with their rationale, preventing re-deciding the same topics.
Storage Structure
All data is stored locally in your project's .claude/tenax/ directory:
.claude/tenax/
├── config.json # User configuration
├── index.json # Accumulated knowledge index
├── embeddings.db # Vector store (sqlite-vec)
└── sessions/
├── 001.json # Processed session data
├── 001.jsonl # Raw transcript
├── 002.json
├── 002.jsonl
└── ...| File | Purpose |
|---|---|
config.json | Your settings (token budget, auto-load, etc.) |
index.json | All decisions, patterns, tasks, insights across sessions |
embeddings.db | SQLite database with vector embeddings for semantic search |
*.jsonl | Raw conversation transcript (full fidelity) |
*.json | Processed session with extracted knowledge |
Token Economics
Understanding token costs helps you manage your context budget effectively. Tenax uses progressive disclosure to minimize overhead:
| Component | Tokens | When Loaded |
|---|---|---|
| Skill description | ~50 | Always (at startup) |
| SKILL.md (full) | ~800 | First trigger on architecture discussion |
| Search result (typical) | 200-500 | Each search query |
| Quick summary | ~500 | Auto-load or /status |
| Full session (typical) | 5,000-20,000 | Explicit load only |
Budget-Aware Loading
The /tenax:load-sessions command respects your configured token budget. It loads sessions in order until the budget would be exceeded, then stops.
Every load operation reports exact token counts, so you always know what you're spending:
Loaded 3 of 5 sessions (12,450 tokens - 15.6% of budget)