Architecture

AI Workspace is organized around explicit boundaries: profile configuration, raw evidence, canonical memory, derived retrieval, local services, and AI client adapters.

System Flow

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:

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.

2.6 KiB Raw Blame History