99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
# 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.
|