Skip to main content

Configuration

The athena.core.config module provides centralized configuration, path discovery, and directory structure for the Athena Operating System.

Overview

from athena.core.config import (
    PROJECT_ROOT,
    AGENT_DIR,
    CONTEXT_DIR,
    MEMORY_DIR,
    get_current_session_log,
    get_active_memory_paths
)

Project Root Discovery

get_project_root()

Discovers the workspace root by searching for pyproject.toml. Results are cached after first call.
from pathlib import Path

def get_project_root() -> Path:
    """
    Discover project root by looking for 'pyproject.toml'.
    Caches the result after the first call.
    """
Discovery Strategy:
  1. Walk up from athena/core/config.py to find pyproject.toml
  2. Fallback to ATHENA_ROOT environment variable
  3. Final fallback to Path.cwd()
Example:
from athena.core.config import get_project_root

root = get_project_root()
print(root)  # /home/user/athena
Caching:
# Global cache
_PROJECT_ROOT_CACHE: Optional[Path] = None

# First call: walks filesystem
root1 = get_project_root()  # ~5ms

# Subsequent calls: uses cache
root2 = get_project_root()  # <0.1ms

Directory Structure

Core Directories

PROJECT_ROOT = get_project_root()

# Key Directories
AGENT_DIR = PROJECT_ROOT / ".agent"
CONTEXT_DIR = PROJECT_ROOT / ".context"
FRAMEWORK_DIR = PROJECT_ROOT / ".framework"
PUBLIC_DIR = PROJECT_ROOT / "Athena-Public"
SCRIPTS_DIR = AGENT_DIR / "scripts"
MEMORIES_DIR = CONTEXT_DIR / "memories"
SESSIONS_DIR = MEMORIES_DIR / "session_logs"
MEMORY_DIR = PROJECT_ROOT / ".athena" / "memory"
STATE_DIR = AGENT_DIR / "state"
INPUTS_DIR = CONTEXT_DIR / "inputs"

Directory Reference

DirectoryPathPurpose
AGENT_DIR.agent/Skills, workflows, scripts
CONTEXT_DIR.context/Memory bank, session logs
FRAMEWORK_DIR.framework/Core identity, protocols
PUBLIC_DIRAthena-Public/Public-facing documentation
SCRIPTS_DIR.agent/scripts/Automation scripts
MEMORIES_DIR.context/memories/Long-term memory storage
SESSIONS_DIR.context/memories/session_logs/Session transcripts
MEMORY_DIR.athena/memory/User profile, learnings
STATE_DIR.agent/state/Runtime state, cache
INPUTS_DIR.context/inputs/Input staging area

Key Files

MANIFEST_PATH = STATE_DIR / "sync_manifest.json"
SYSTEM_LEARNINGS_FILE = MEMORY_DIR / "SYSTEM_LEARNINGS.md"
USER_PROFILE_FILE = MEMORY_DIR / "USER_PROFILE.yaml"
TAG_INDEX_PATH = CONTEXT_DIR / "TAG_INDEX.md"
TAG_INDEX_AM_PATH = CONTEXT_DIR / "TAG_INDEX_A-M.md"
TAG_INDEX_NZ_PATH = CONTEXT_DIR / "TAG_INDEX_N-Z.md"
CANONICAL_PATH = CONTEXT_DIR / "CANONICAL.md"
Tag Index Sharding: For token efficiency, the tag index is split into two files:
  • TAG_INDEX_A-M.md - Tags starting with A-M
  • TAG_INDEX_N-Z.md - Tags starting with N-Z
  • TAG_INDEX.md - Legacy monolithic (for backwards compatibility)

Active Memory Configuration

Core Memory Directories

CORE_DIRS = {
    "sessions": SESSIONS_DIR,
    "case_studies": MEMORIES_DIR / "case_studies",
    "protocols": AGENT_DIR / "skills" / "protocols",
    "capabilities": AGENT_DIR / "skills" / "capabilities",
    "workflows": AGENT_DIR / "workflows",
    "system_docs": FRAMEWORK_DIR / "v8.2-stable" / "modules",
}

Extended Memory Silos

Extended directories are mapped to logical memory tables:
EXTENDED_DIRS = [
    (PROJECT_ROOT / "analysis", "case_studies"),
    (PROJECT_ROOT / "Marketing", "system_docs"),
    (PROJECT_ROOT / "proposals", "case_studies"),
    (PROJECT_ROOT / "Winston", "system_docs"),
    (PROJECT_ROOT / "docs" / "audit", "system_docs"),
    (PROJECT_ROOT / "gem_knowledge_base", "system_docs"),
    (PROJECT_ROOT / ".athena", "system_docs"),
    (PROJECT_ROOT / ".projects", "system_docs"),
    (PROJECT_ROOT / "Reflection Essay", "case_studies"),
    (CONTEXT_DIR / "research", "case_studies"),
    (CONTEXT_DIR / "specs", "system_docs"),
]
Table Mappings:
  • "sessions" - Session logs and transcripts
  • "case_studies" - Analysis, proposals, reflections
  • "protocols" - Protocol definitions
  • "capabilities" - Capability specifications
  • "workflows" - Workflow definitions
  • "system_docs" - Documentation, knowledge base

get_active_memory_paths()

Returns a deduplicated list of all active memory directories.
def get_active_memory_paths() -> list[Path]:
    """Returns a deduplicated list of all active memory directory Paths."""
    paths = [p for p in CORE_DIRS.values() if p.exists()]
    paths.extend([p for p, _ in EXTENDED_DIRS if p.exists()])
    return sorted(list(set(paths)))
Example:
from athena.core.config import get_active_memory_paths

paths = get_active_memory_paths()
for path in paths:
    print(path)
Output:
/home/user/athena/.agent/skills/protocols
/home/user/athena/.agent/workflows
/home/user/athena/.context/memories/case_studies
/home/user/athena/.context/memories/session_logs
/home/user/athena/.framework/v8.2-stable/modules
/home/user/athena/analysis
/home/user/athena/proposals

Session Management

get_current_session_log()

Finds the most recent session log file.
from typing import Optional
from pathlib import Path

def get_current_session_log() -> Optional[Path]:
    """
    Find the most recent session log file (pattern: YYYY-MM-DD-session-XX.md).
    """
Pattern Matching:
  • Format: YYYY-MM-DD-session-XX.md
  • Example: 2026-03-03-session-42.md
Sorting:
  1. Sort by date (descending)
  2. Then by session number (descending)
Example:
from athena.core.config import get_current_session_log

current = get_current_session_log()
if current:
    print(f"Current session: {current.name}")
    content = current.read_text()
else:
    print("No session logs found")
Implementation:
import re
from pathlib import Path

if not SESSIONS_DIR.exists():
    return None

pattern = re.compile(r"(\d{4}-\d{2}-\d{2})-session-(\d{2,3})\.md")
session_files = []

for f in SESSIONS_DIR.glob("*.md"):
    match = pattern.match(f.name)
    if match:
        date_str, session_num = match.groups()
        session_files.append((date_str, int(session_num), f))

if not session_files:
    return None

# Sort by date then session number descending
session_files.sort(key=lambda x: (x[0], x[1]), reverse=True)
return session_files[0][2]

Environment Variables

ATHENA_ROOT

Optional override for project root discovery.
export ATHENA_ROOT=/custom/path/to/athena
python3 -m athena.boot.orchestrator
Priority:
  1. pyproject.toml discovery (highest)
  2. ATHENA_ROOT environment variable
  3. Path.cwd() (fallback)

Usage Patterns

Accessing Configuration

from athena.core.config import (
    PROJECT_ROOT,
    SESSIONS_DIR,
    MEMORY_DIR,
    get_current_session_log
)

# Read current session
session = get_current_session_log()
if session:
    content = session.read_text()

# List all session logs
for log in sorted(SESSIONS_DIR.glob("*.md")):
    print(log.name)

# Access user profile
user_profile = MEMORY_DIR / "USER_PROFILE.yaml"
if user_profile.exists():
    profile_data = user_profile.read_text()

Dynamic Path Construction

from athena.core.config import PROJECT_ROOT

# Build paths relative to project root
custom_dir = PROJECT_ROOT / "custom" / "subdirectory"
custom_dir.mkdir(parents=True, exist_ok=True)

config_file = custom_dir / "config.json"
config_file.write_text('{"enabled": true}')

Memory Path Iteration

from athena.core.config import get_active_memory_paths

# Process all active memory directories
for path in get_active_memory_paths():
    if path.exists():
        for md_file in path.glob("**/*.md"):
            # Process markdown files
            pass

Performance Considerations

Caching:
  • get_project_root() caches result globally
  • First call: ~5ms (filesystem traversal)
  • Subsequent calls: Less than 0.1ms (cache lookup)
Best Practices:
# Good: Import constants directly
from athena.core.config import PROJECT_ROOT, SESSIONS_DIR

# Avoid: Repeated function calls
for _ in range(1000):
    root = get_project_root()  # Uses cache, but still overhead

# Better: Use module-level constant
for _ in range(1000):
    root = PROJECT_ROOT  # Direct access, no function call

See Also

Build docs developers (and LLMs) love