Storage Model

AIWorkspace uses different storage locations for different kinds of data. This keeps the product shareable, the project context auditable, and local runtime state disposable.

Storage Responsibilities

Data	Target Location	Git?	Notes
Core product code	`~/Developer/ai-workspace`	yes	Shared reusable product.
Project manifest	`<context-pack>/aiw.project.json`	yes	Project identity and relative paths.
Canonical memory	`<context-pack>/knowledge/`	usually yes	Human-readable Markdown.
Raw evidence	`<context-pack>/inbox/`	usually no/private	Captured messages, screenshots, exports.
Connector config	`<context-pack>/connectors/`	depends	Safe config can be tracked; secrets must not be tracked.
Project prompts/agents	`<context-pack>/prompts/`, `<context-pack>/agents/`	depends	Track if safe for the team.
User registry	`~/Library/Application Support/AIWorkspace/`	no	Local project registration and preferences.
Logs	`~/Library/Logs/AIWorkspace/`	no	Service and app logs.
Caches/indexes	`~/Library/Caches/AIWorkspace/`	no	Rebuildable derived data.
Runtime/PIDs	`~/Library/Application Support/AIWorkspace/runtime/`	no	Local service state.

Canonical Memory

Canonical memory is the durable project source of truth for humans and AI.

Target structure:

knowledge/
  current/
  work-items/
  systems/
  workstreams/
  people/
  decisions/
  daily/
  templates/

Canonical memory should be:

readable without AIWorkspace;
reviewable in Git when shared;
explicit about uncertainty;
updated by humans or agents using small auditable changes.

Raw Evidence

Raw evidence is input, not truth.

Examples:

inbox/
  mattermost/
  slack/
  photos/
  documents/
  screenshots/

Raw evidence should not be promoted automatically into durable memory unless a workflow explicitly classifies it as high-confidence and project-relevant.

Derived Indexes

Indexes are rebuildable.

They should live outside the context pack by default:

~/Library/Caches/AIWorkspace/indexes/<project>/

This prevents large derived artifacts from polluting project memory repositories.

Runtime State

Service logs, PID files, and health snapshots should be local machine state.

Target locations:

~/Library/Logs/AIWorkspace/
~/Library/Application Support/AIWorkspace/runtime/

Runtime state should not be used as project memory.

Secrets

Secrets should not be stored in context packs unless they are encrypted and explicitly supported.

Preferred approaches:

macOS Keychain references;
ignored local .env files;
environment variables;
enterprise-approved credential stores.

Documentation, manifests, and generated configs should refer to secret names, not secret values.

2.8 KiB Raw Blame History