AETHER_ARCHITECTURE.md

Aether Architecture

The Problem It Solves

When working with an AI assistant across multiple conversations, context gets lost. You tell it to build X, then on the next prompt it forgets and builds Y. Aether solves this with persistent context injection.

How It Works

1. Project Context Storage

Each project stores:

• Name: Unique identifier
• Description: What the project is about
• Goal: What you're trying to achieve
• Status: Current state (active, paused, completed)

2. Context Injection

Before every Claude call, Aether builds a system prompt that includes:

You are working on: [project name]
Description: [project description]
Goal: [project goal]

Recent decisions:
- [decision 1] (because: [reason])
- [decision 2] (because: [reason])

Recent work:
- User: [last question]
  You: [your response]

This ensures Claude always has the full context.

3. Conversation Tracking

Two types of conversations:

Single-turn chat: One-off questions

• Logged to conversations table
• Useful for quick queries
• No multi-turn history

Multi-turn sessions: Ongoing conversations

• Full message history maintained in session_messages
• Claude sees entire conversation thread
• Useful for design discussions, debugging, planning

4. Decision Recording

Important decisions are recorded with reasoning:

• Decision: "Use React hooks instead of class components"
• Reason: "Simpler state management and better code reuse"
• Timestamp: When it was decided

These appear in the system prompt for all future conversations.

Database Schema

projects
├── id (PK)
├── name (UNIQUE)
├── description
├── goal
├── status
└── created_at

conversations
├── id (PK)
├── project_id (FK)
├── user_message
├── ai_response
└── timestamp

decisions
├── id (PK)
├── project_id (FK)
├── decision
├── reason
└── timestamp

sessions
├── id (PK)
├── project_id (FK)
├── session_name
└── created_at

session_messages
├── id (PK)
├── session_id (FK)
├── role (user/assistant)
├── content
└── timestamp

Usage Patterns

Pattern 1: Quick Questions

python aether.py chat "my-project" "How do I handle async errors?"

• One-off question
• Claude gets project context
• Response logged but no multi-turn history

Pattern 2: Design Discussion

python aether.py session "my-project" "architecture" "Should we use microservices?"
python aether.py session "my-project" "architecture" "What about deployment complexity?"
python aether.py session "my-project" "architecture" "How do we handle data consistency?"

• Full conversation history maintained
• Claude sees entire thread
• Perfect for iterative design

Pattern 3: Decision Tracking

python aether.py decide "my-project" "Use PostgreSQL" "Better for relational data, ACID guarantees"

• Records why a decision was made
• Appears in all future conversations
• Prevents revisiting settled questions

Why This Works

1. Simple: Just SQLite + prompt injection. No complex pipelines.
2. Effective: Claude already understands context. Just feed it.
3. Persistent: Everything is logged. You can review history anytime.
4. Flexible: Works for any type of project or conversation.
5. Transparent: You can see exactly what context Claude receives.

Example Workflow

# Start a new project
python aether.py new "api-redesign" "REST API redesign" "Improve performance and consistency"

# Have a design discussion
python aether.py session "api-redesign" "design" "What's the best approach for versioning?"
# Claude responds with suggestions

# Continue the discussion
python aether.py session "api-redesign" "design" "Should we use URL paths or headers?"
# Claude remembers the previous conversation

# Record the decision
python aether.py decide "api-redesign" "Use URL versioning" "Clearer for clients, easier to deprecate"

# Ask a follow-up
python aether.py session "api-redesign" "design" "How do we handle backward compatibility?"
# Claude sees the decision in context and builds on it

# Check project status
python aether_status.py show "api-redesign"
# See all decisions, conversations, and sessions

Integration

You can also use Aether programmatically:

from aether import Aether

aether = Aether()
aether.new_project("my-project", "description", "goal")
response = aether.session_chat("my-project", "session-name", "your message")
aether.record_decision("my-project", "decision", "reason")

What's NOT Included

• No consciousness pipeline
• No threat detection
• No ethics validation
• No keyword matching
• No 28-expert councils
• No complex state machines

Just: database + prompt injection + logging. That's it.