69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# Architecture
|
|
|
|
AI Workspace is organized around explicit boundaries: profile configuration, raw evidence, canonical memory, derived retrieval, local services, and AI client adapters.
|
|
|
|
## System Flow
|
|
|
|
```text
|
|
Communication / screenshots / archives / manual notes
|
|
↓
|
|
Raw inbox evidence
|
|
↓
|
|
Agent or human curation
|
|
↓
|
|
Canonical Markdown project knowledge
|
|
↓
|
|
Derived local index
|
|
↓
|
|
Read-only MCP context server
|
|
↓
|
|
AI clients and agent workflows
|
|
```
|
|
|
|
## Responsibility Boundaries
|
|
|
|
| Layer | Responsibility | Canonical? |
|
|
|---|---|---|
|
|
| `core/` | Reusable architecture and operating model | yes, for workspace design |
|
|
| `profiles/<profile>/` | Project-specific configuration and assumptions | yes, for profile config |
|
|
| `project-knowledge/` | Human-readable project memory for the active profile | yes, for project facts |
|
|
| `ai/inbox/` | Raw evidence captured from connectors | no |
|
|
| `.aiw/indexes/` | Rebuildable search indexes | no |
|
|
| `.aiw/runtime/` | PID files, logs, local service state | no |
|
|
| `scripts/aiw/` | Profile-aware service/index utilities | code source |
|
|
| `scripts/mcp/` | MCP servers exposing local context | code source |
|
|
| `apps/` | Local UI surfaces such as the macOS menu bar app | code source |
|
|
|
|
## Current Repository Shape
|
|
|
|
The current repo still keeps the first real profile's vault at root-level `project-knowledge/`. That is acceptable during migration, but reusable code should increasingly resolve paths from profile configuration rather than hardcoding Fidelity-specific locations.
|
|
|
|
Target direction:
|
|
|
|
```text
|
|
profiles/<profile>/workspace.json # where profile data lives
|
|
workspaces/<profile>/project-knowledge/
|
|
workspaces/<profile>/inbox/
|
|
.aiw/indexes/<profile>/
|
|
```
|
|
|
|
## Design Principles
|
|
|
|
- Keep the smallest useful context loaded by default.
|
|
- Prefer just-in-time retrieval over dumping the entire workspace into prompts.
|
|
- Keep human-readable Markdown as the project source of truth.
|
|
- Keep raw evidence outside canonical memory until explicitly promoted.
|
|
- Keep profile-specific facts out of `core/` and generic scripts.
|
|
- Make local services observable through a single service manager.
|
|
- Treat cloud memory systems as optional, not authoritative.
|
|
|
|
## Why This Shape
|
|
|
|
Current AI workflow guidance emphasizes context engineering: the model should receive the smallest high-signal context needed for the task. This workspace supports that by combining:
|
|
|
|
- structured Markdown memory for durable facts;
|
|
- raw evidence stores for auditability;
|
|
- local indexes for retrieval;
|
|
- MCP tools/resources for AI clients;
|
|
- profile-specific boundaries for reuse across projects.
|