xonecas.io
60255
Zn

Zoea-Nova / commit 8250f37

docs: update README and AGENTS.md with context compression

README:
- Add context compression and memory search to features list
- Fix preview.gif filename typo (was prview.gif)

AGENTS.md:
- Add context compression terminology with doc link
- Add testing note about t.TempDir() for database isolation
- Fix coverage target (80%, currently ~61%)
- Fix plans directory path (.opencode/plans/)

xonecas2026-02-04 8250f3796f66b6977528b4eb3e86856112e9b1b0 parent 2040f73

3 files changed

AGENTS.md+12−2
@@ -13,7 +13,7 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
1313 - Use interfaces for external dependencies (LLM providers, MCP, store).
1414 - Run `make fmt` before committing. Fix all warnings and linter errors.
1515 - When committing, use `required_permissions: ["all"]` to bypass sandbox restrictions (GPG signing requires full filesystem access).
16-- Write unit tests for all modules. Target 95%+ coverage.
16+- Write unit tests for all modules. Target 80%+ coverage (currently ~61%).
1717 - Never write data migrations. Schema changes require a fresh database.
1818 - Use `zerolog` for logging. Never log to stdout/stderr (TUI owns the terminal).
1919 - Keep the TUI responsive. All LLM/network calls must be non-blocking (goroutines + channels).
@@ -42,6 +42,15 @@ Multi-byte Unicode characters cause width calculation bugs:
4242 - **Style padding affects alignment**: `lipgloss.Style.Padding(0, 1)` adds 1 space on each side. If one element has padding and another doesn't, their decorations won't align even if both are "width" chars total.
4343 - **`lipgloss.Width()` sets content width**: When using `style.Width(n)`, the `n` sets the CONTENT width. Borders and padding are added ON TOP. So `style.Width(98)` with a border produces total width 100.
4444
45+## Database Management:
46+
47+The application uses SQLite for persistence.
48+
49+- **Location**: `~/.zoea-nova/zoea.db`
50+- **Querying**: Use `sqlite3 ~/.zoea-nova/zoea.db` to run manual queries.
51+- **Wiping**: To reset the state or apply schema changes (since migrations are not supported), delete the database and its temporary files: `rm ~/.zoea-nova/zoea.db*`.
52+- **Testing**: Tests use `t.TempDir()` for isolated database files. Never use the production database path in tests.
53+
4554 ## Terminology:
4655
4756 - **Agent**: An AI-controlled player instance with its own provider, memory, and state.
@@ -54,13 +63,14 @@ Multi-byte Unicode characters cause width calculation bugs:
5463 - **Dashboard**: TUI view showing swarm status, broadcast history, and agent list.
5564 - **Memory**: A stored conversation message with role (system/user/assistant/tool) and source.
5665 - **Source**: Origin of a memory—`direct` (single agent), `broadcast` (swarm), `system`, `llm`, or `tool`.
66+- **Context Compression**: Sliding window that sends only recent messages + system prompt to LLM. See [documentation/CONTEXT_COMPRESSION.md](documentation/CONTEXT_COMPRESSION.md).
5767
5868 ## Workflow:
5969
6070 The user follows a structured development workflow. Respect these phases:
6171
6272 1. **Design**: Documentation for this project is in `documentation/` Keep it up to date and accurate.
63-2. **Plan**: Complex changes require a plan in `.cursor/plans/`. Reference the plan while implementing.
73+2. **Plan**: Complex changes require a plan in `.opencode/plans/`. Reference the plan while implementing.
6474 3. **Implement**: Follow the plan phase-by-phase. Update tests alongside code, add more as needed.
6575 4. **Test**: Run `make test` after each phase. Fix failures before moving on.
6676 5. **Build**: Run `make build` to verify compilation. Address any warnings.
README.md+22−13
@@ -8,6 +8,13 @@ Zoea-Nova is a high-performance command center designed to orchestrate massive s
88
99 > **It's actually just a fancy TUI App to control several mcp clients for the game: [SpaceMolt](https://www.spacemolt.com/)**
1010
11+## Preview
12+
13+<br />
14+<p align="center">
15+ <img src="assets/preview.gif" width="800" alt="Zoea-Nova Preview">
16+</p>
17+
1118 ## Features
1219
1320 - **Swarm Control**: Create and manage multiple AI agents, each with independent memory and LLM provider
@@ -16,6 +23,8 @@ Zoea-Nova is a high-performance command center designed to orchestrate massive s
1623 - **Tool Calling**: Agents use MCP to interact with SpaceMolt (mine, trade, navigate, etc.)
1724 - **Focus Mode**: View detailed conversation logs for any agent
1825 - **Provider Flexibility**: Use local Ollama or remote OpenCode Zen models per-agent
26+- **Context Compression**: Sliding window keeps LLM context small for fast inference while full history remains searchable (see [documentation](documentation/CONTEXT_COMPRESSION.md))
27+- **Memory Search**: Agents can search past messages and broadcasts to recall older information
1928
2029 ## Try it
2130
@@ -27,16 +36,16 @@ make run # Build and start
2736
2837 ## Keyboard Shortcuts
2938
30-| Key | Action |
31-|-----|--------|
32-| `n` | Create new agent |
33-| `b` | Broadcast message to all |
34-| `m` | Message selected agent |
35-| `r` | Relaunch agent |
36-| `s` | Stop agent |
37-| `d` | Delete agent |
38-| `c` | Configure agent |
39-| `Enter` | Focus on selected agent |
40-| `Esc` | Return to dashboard |
41-| `?` | Show help |
42-| `q` | Quit |
39+| Key | Action |
40+| ------- | ------------------------ |
41+| `n` | Create new agent |
42+| `b` | Broadcast message to all |
43+| `m` | Message selected agent |
44+| `r` | Relaunch agent |
45+| `s` | Stop agent |
46+| `d` | Delete agent |
47+| `c` | Configure agent |
48+| `Enter` | Focus on selected agent |
49+| `Esc` | Return to dashboard |
50+| `?` | Show help |
51+| `q` | Quit |
assets/preview.gif+0−0
Binary file, not shown.