# era3000 Kora | Complete Architectural Blueprints & Extended Specs

This document represents the complete system design, folder mapping, and operational parameters of Kora's Agentic AI platform.

---

## 1. Directory Structure & Folder Mappings

Kora maintains strict modular boundaries. When running in self-hosted or SaaS multiuser environments, Kora operates on the following folder structure:

```
/kora/
├── .well-known/           # Standard agent discovery protocols
├── assets/                # Visual mockups and logos
├── backend/               # Main runtime (TypeScript, Node.js)
│   ├── src/
│   │   ├── agents/        # Cognitive swarms and reasoning loops
│   │   ├── tools/         # Integrated MCP tools (crawling, SMTP)
│   │   └── index.ts       # Service entry point
│   ├── package.json
│   └── tsconfig.json
├── frontend/              # Admin console and customer self-service portals
│   ├── css/
│   ├── js/
│   └── index.html
├── data/                  # SQLite storage, isolated browser sessions, and vector databases
│   ├── workspaces/        # Per-user isolated workspace sandboxes
│   │   └── [workspace-id]/
│   │       ├── sandbox/   # Restricted execution folder
│   │       ├── vector/    # Local Qdrant/Chroma index files
│   │       └── MEMORY.md  # Factual long-term memory records
└── docker-compose.yml     # Multi-user SaaS production setup file
```

---

## 2. Multi-Tiered Neural Memory Compaction Model

To eliminate context rot and minimize token consumption, Kora employs a self-consolidating memory structure:

```
[User Interaction] -> [Memory Extraction Agent] -> [Importance Assessment]
                                                         │
   ┌─────────────────────────────────────────────────────┘
   ▼
[Short-Term Context] (decay score) -> [Stale Pruned]
   ▼
[Long-Term Facts] -> [Merged with MEMORY.md Profile]
```

### Compaction Algorithm Specifics
1. **Extraction**: After each transaction, a background `kyu_agent` extracts facts, preferences, and operational objectives.
2. **Importance Scoring**: Facts are given a priority rank (1 to 10) and an access-recency timestamp.
3. **Compaction Cycle**: Stale or duplicate entries are merged. Inactive, low-scoring memory records are pruned when prompt space is constrained.
4. **Context Injection**: Less than 30 top-priority, consolidated memory records are loaded into the LLM system prompt context dynamically during execution.

---

## 3. Isolated Browser Sandboxing & Failsafes

When executing interactive actions (crawling, executing shell scripts, managing server actions), Kora guarantees multi-tenant security:

1. **Docker Isolation**: Each workspace session runs its headless browser inside a dynamically spawned `CloakBrowser` container.
2. **System Safeguards**: Host filesystem access is forbidden. Tools interact strictly inside `/data/workspaces/[workspace-id]/sandbox/`.
3. **Human-in-the-Loop Failsafes**: Highly sensitive tools (such as deleting databases, installing new MCP plugins, or initiating billing parameters) trigger validation alerts requiring explicit manual approval.