# 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:

```text
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:

```text
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:

```text
~/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:

```text
~/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.