Memory System

The Memory System is what makes Tevis more than a stateless AI tool. It captures knowledge, decisions, patterns, and lessons from your work—building a persistent understanding that improves over time.

Why Memory Matters

Traditional AI interactions are stateless:

Session 1: "Use Repository pattern for data access"
Session 2: AI doesn't remember, suggests Active Record
Session 3: You explain again...

With Tevis Memory:

Session 1: "Use Repository pattern for data access"
           → Captured as architectural decision

Session 2: AI remembers, suggests Repository pattern
Session 3: Pattern consistently applied
           → Compounds over time

Memory Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      MEMORY SYSTEM                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐    ┌─────────────────┐                     │
│  │    Extractor    │    │   Retriever     │                     │
│  │    (Capture)    │    │   (Recall)      │                     │
│  └────────┬────────┘    └────────┬────────┘                     │
│           │                      │                               │
│           └──────────┬───────────┘                               │
│                      │                                           │
│              ┌───────▼───────┐                                   │
│              │    Memory     │                                   │
│              │    Store      │                                   │
│              └───────────────┘                                   │
│                      │                                           │
│      ┌───────────────┼───────────────┐                          │
│      │               │               │                          │
│  ┌───▼───┐      ┌────▼────┐    ┌─────▼─────┐                    │
│  │Decisions│    │ Patterns │   │  Lessons  │                    │
│  └────────┘    └──────────┘   └───────────┘                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Memory Types

Decisions

Architectural and design decisions:

{
  "type": "decision",
  "content": "Use Repository pattern for all database access",
  "context": "Discussed during NC-003 planning",
  "rationale": "Better testability, separation of concerns",
  "timestamp": "2026-01-15T10:30:00Z",
  "confidence": 0.95
}

Examples:

• "Use JWT tokens, not session cookies"
• "Prefer composition over inheritance"
• "API versioning via URL path (/v1/, /v2/)"
• "Error responses follow RFC 7807"

Patterns

Recurring implementation patterns:

{
  "type": "pattern",
  "content": "Error handling in API endpoints",
  "example": "try/except with HTTPException, logging, and standard error response",
  "files": ["src/api/users.py:45", "src/api/projects.py:32"],
  "frequency": 12,
  "confidence": 0.9
}

Examples:

• "API endpoint structure"
• "Component file organization"
• "Test naming conventions"
• "Logging format and levels"

Lessons

What worked, what didn't:

{
  "type": "lesson",
  "content": "Avoid raw SQL queries in route handlers",
  "source": "NC-005 bug fix",
  "impact": "Caused SQL injection vulnerability",
  "resolution": "Use ORM exclusively, add SQLi testing",
  "timestamp": "2026-01-20T14:00:00Z",
  "confidence": 0.98
}

Examples:

• "Migration X caused downtime—test migrations on staging first"
• "Library Y has memory leak—prefer library Z"
• "Approach A failed for reason B—use approach C instead"

Preferences

Your coding style and preferences:

{
  "type": "preference",
  "content": "Prefer explicit type annotations",
  "examples": ["Always annotate function parameters", "Use TypedDict for dictionaries"],
  "confidence": 0.85
}

Examples:

• "Prefer functional over OOP for utilities"
• "Use descriptive variable names over comments"
• "Test file next to source file, not in separate directory"

Memory Extraction

Automatic Extraction

Tevis extracts memory from:

Task Completion:

TPU completes T005: Add user validation
                      ↓
Extract: "Input validation pattern: Pydantic models with custom validators"

Feature Completion:

Feature auth-api complete
                      ↓
Extract: "Authentication flow: JWT access + refresh tokens, bcrypt hashing"

Errors and Fixes:

Test failure → Investigation → Fix
                      ↓
Extract: "Lesson: Mock external services in tests to avoid flaky failures"

Hold Points:

Hold point: "Which approach for caching?"
Decision: Redis with 5-minute TTL
                      ↓
Extract: "Decision: Use Redis for caching, 5-minute default TTL"

Manual Memory Addition

Add memories explicitly:

# CLI
tevis memory add "Always use UTC for timestamps in the database"

# With type
tevis memory add --type decision "Use PostgreSQL, not SQLite, for production"

# With context
tevis memory add "Repository pattern for data access" \
  --context "Architecture decision from Q1 planning"

Memory Retrieval

Context Building

When generating plans or guidance, relevant memories are retrieved:

Query: "Add user settings page"
                 ↓
Retrieve related memories:
- Decision: "Use React for all UI components"
- Pattern: "Form validation with Zod"
- Preference: "Settings stored in user object, not separate table"
- Lesson: "Add loading states to prevent double-submit"
                 ↓
Include in LPU context

Relevance Scoring

Memories are scored for relevance:

Query: "Add payment processing"

Memory: "Use Stripe for payments"
  - Type match: decision ✓
  - Keyword match: "payment" ✓
  - Recency: 2 weeks ago
  - Confidence: 0.95
  Score: 0.92 → Include

Memory: "Use Repository pattern"
  - Type match: decision ✓
  - Keyword match: none
  - Recency: 1 month ago
  - Confidence: 0.90
  Score: 0.45 → Maybe include

Memory: "Fix typo in README"
  - Type match: lesson
  - Keyword match: none
  - Recency: 3 months ago
  Score: 0.05 → Exclude

Retrieval Limits

Not all memories are included (context limits):

lpu:
  context:
    memory_limit: 50        # Max memories to include
    memory_types:           # Types to include
      - decision
      - pattern
      - lesson
      - preference
    min_relevance: 0.3      # Minimum relevance score

Memory Storage

Local Storage

Primary storage in your knowledge base:

~/.tevis/accounts/{account}/projects/{project}/kb/
├── memories/
│   ├── decisions.json
│   ├── patterns.json
│   ├── lessons.json
│   └── preferences.json
└── ...

Cloud Sync

Summaries synced to Tevis Core:

Local (full):           Cloud (summary):
{                       {
  "type": "decision",     "type": "decision",
  "content": "...",       "summary": "JWT auth",
  "context": "...",       "timestamp": "...",
  "rationale": "..."      "id": "mem_abc123"
}                       }

Full content stays local; summaries enable cross-device search.

Managing Memories

List Memories

# All memories
tevis memory list

# By type
tevis memory list --type decision

# Search
tevis memory search "authentication"

View Memory Details

tevis memory show mem_abc123

# Output
ID: mem_abc123
Type: decision
Content: Use JWT tokens with 15-minute access, 7-day refresh
Context: Established during NC-003 auth implementation
Rationale: Balance security (short access) with UX (long refresh)
Created: 2026-01-15 10:30:00
Confidence: 0.95
References: 5 (NC-003, NC-005, NC-007...)

Edit Memory

# Update content
tevis memory edit mem_abc123 --content "Updated content"

# Update confidence
tevis memory edit mem_abc123 --confidence 0.8

# Add context
tevis memory edit mem_abc123 --context "Additional context"

Delete Memory

# Delete single memory
tevis memory delete mem_abc123

# Delete by type (with confirmation)
tevis memory delete --type lesson --before 2025-01-01

Memory Quality

Confidence Scores

Memories have confidence scores (0.0 - 1.0):

Score	Meaning	Example
0.9+	Strong, verified	Explicit decision, repeatedly confirmed
0.7-0.9	Likely accurate	Inferred from consistent behavior
0.5-0.7	Moderate	Single observation, reasonable confidence
< 0.5	Uncertain	Weak signal, may be outdated

Confidence Decay

Memories not reinforced lose confidence over time:

Initial: 0.95
After 1 month unused: 0.90
After 3 months unused: 0.80
After 6 months unused: 0.65

Reinforcement (memory used and validated) resets decay.

Conflict Resolution

When memories conflict:

Memory A: "Use SQLite for database"
Memory B: "Use PostgreSQL for database"

Resolution:
- Compare timestamps (newer may override)
- Compare confidence (higher wins)
- Compare references (more used = more trusted)
- Ask for clarification if ambiguous

Best Practices

Review Extracted Memories

Periodically review what's being captured:

# Recent extractions
tevis memory list --since "1 week ago"

# Review and correct if needed
tevis memory edit mem_xyz --content "Corrected content"

Curate Important Decisions

Don't rely only on automatic extraction:

# After major decisions, capture explicitly
tevis memory add --type decision \
  "Microservices architecture: auth, api, worker, scheduler services" \
  --context "Q1 2026 architecture review"

Clean Up Outdated Memories

Remove memories that no longer apply:

# Find old memories
tevis memory list --before "6 months ago" --low-confidence

# Review and delete if obsolete
tevis memory delete mem_old123

Use Memory in Planning

Reference memories when creating nanocycles:

tevis nanocycle create \
  --description "Add payment processing" \
  --include-memories "payment,billing,stripe"

Troubleshooting

Missing Memories

Memories not being extracted:

# Check extraction is enabled
tevis config get memory.auto_extract

# Enable if disabled
tevis config set memory.auto_extract true

# Check minimum confidence for storage
tevis config get memory.min_confidence

Too Many Irrelevant Memories

LPU context cluttered:

# Increase relevance threshold
tevis config set lpu.context.min_relevance 0.5

# Reduce memory limit
tevis config set lpu.context.memory_limit 30

Memory Conflicts

Contradictory memories causing confusion:

# Find similar memories
tevis memory search "database"

# Resolve conflicts
tevis memory delete mem_outdated
tevis memory edit mem_current --confidence 0.95