# Data Architecture — Where Information Lives

Three layers feed the AI. Each has a different purpose, format, owner, and lifecycle.

```
┌─────────────────────────────────────────────────────────┐
│  KNOWLEDGE (prescriptive)                               │
│  "How things SHOULD work"                               │
│  Written by: humans / knowledge-init wizard             │
│  Location: knowledge/ + accounts/<PROFILE>/knowledge/ │
│  Overrides: account > packaged platform knowledge            │
├─────────────────────────────────────────────────────────┤
│  MEMORY (descriptive)                                   │
│  "How things DO work" (observed, not decided)           │
│  Written by: AI (Learning Capture Protocol)             │
│  Location: accounts/<PROFILE>/memory/                   │
│             ~/.claude/projects/.../memory/               │
│  Disposable: delete it, AI re-learns from evidence      │
├─────────────────────────────────────────────────────────┤
│  SKILLS (executable)                                    │
│  "How to do things" (instructions + templates)          │
│  Written by: skill authors                              │
│  Location: fluent-ai-skills/content/                    │
│  Loaded: on invocation only                             │
└─────────────────────────────────────────────────────────┘
```

**When they conflict:** Knowledge wins over memory. Account knowledge wins over packaged platform knowledge.

---

## 1. Knowledge — What goes here

**Purpose:** Team decisions, conventions, contracts, platform facts. Things that are TRUE because the team DECIDED them (naming rules) or because the platform DEFINES them (entity model).

**Owner:** Humans. The AI writes the files, but a human reviews and approves.

**Location:**

| Path | Scope | Example |
|------|-------|---------|
| `knowledge/platform/` | Fluent platform (all accounts) | Entity model, routing architecture, rule contract |
| `knowledge/frontend/` | Packaged UI/platform reference | Mystique SDK, templates, UI patterns |
| `knowledge/templates/` | Reusable packaged templates | Shared deploy/test/spec templates |
| `accounts/<PROFILE>/knowledge/` | This specific account | Naming rules, coding standards, business rules, data model, integrations |

### Format

Every knowledge file has YAML frontmatter:

```markdown
---
name: mystique-routing
description: "One-line summary of what this file covers"
load: on-demand
relevant-skills:
  - mystique-builder
  - mystique-validate
  - ui-test
---

# Title

Content here. Be specific, include examples, say WHY.
```

**Frontmatter fields:**

| Field | Required | Purpose |
|-------|----------|---------|
| `name` | Yes | Unique identifier (kebab-case) |
| `description` | Yes | One-line summary — shown in index.md |
| `load` | Yes | `always` (in CLAUDE.md) or `on-demand` (skills read when relevant) |
| `relevant-skills` | Yes for on-demand | Which skills load this file during pre-flight |

### When to add knowledge

- Team decides a naming convention for one account → `accounts/<PROFILE>/knowledge/naming-conventions.md`
- Platform behavior validated against live schema → `knowledge/platform/` new file
- Client has routing constraints or SLAs → `accounts/<PROFILE>/knowledge/client/business-rules.md`
- You find yourself correcting the AI on the same thing twice → knowledge file

### Example: Adding a new platform knowledge file

```markdown
---
name: mystique-routing
description: "Mystique routing: HashRouter, page params ({{params.id}}), link patterns, backButtons."
load: on-demand
relevant-skills:
  - mystique-builder
  - mystique-validate
  - ui-test
---

# Mystique Routing Architecture

## URL Structure
Mystique uses hash-based routing. All navigation is after `#/`:
https://host/oms/#/orders/6692/2/ORD-001

## Key Rules
- Sections have NO path — sidebar grouping only
- Page query variables use {{params.id}}, NOT {{id}}
- Links require #/ prefix: "#/orders/{{node.id}}/{{node.retailer.id}}/{{node.ref}}"
- backButtons often use relative paths (no #/): "path": "orders"
```

Then register it in `knowledge/index.md` in the On-Demand table.

### Loading strategy

| Strategy | Where configured | When loaded | Example |
|----------|-----------------|-------------|---------|
| **Always** | Referenced in CLAUDE.md | Every conversation | `partner/naming-conventions.md` |
| **On-demand** | `relevant-skills` in frontmatter | Skill pre-flight reads matching files | `platform/domain-model.md` |
| **Skill-triggered** | Skill reads explicitly | Skill needs a template/checklist | `templates/deploy-checklist.md` |

---

## 2. Memory — What goes here

**Purpose:** Observed patterns, gotchas, corrections, runtime evidence. Things that are TRUE because the AI SAW them happen (deploy failures, API quirks, schema surprises).

**Owner:** AI. Writes automatically when it learns something. No human review required.

**Location:**

| Path | Scope | Loaded when |
|------|-------|-------------|
| `~/.claude/projects/.../memory/MEMORY.md` | Global (cross-project) | Always (first 200 lines) |
| `~/.claude/projects/.../memory/<topic>.md` | Global topic files | When relevant to current task |
| `accounts/<PROFILE>/memory/index.md` | Account-specific summary | Session start (when FLUENT_PROFILE set) |
| `accounts/<PROFILE>/memory/learnings.md` | Account-specific detail | When deeper context needed |

### Format

**Global MEMORY.md** — flat sections, concise bullets:

```markdown
# Fluent AI Workspace Memory

## Topic Files
- [graphql-patterns.md](graphql-patterns.md) — Schema gotchas, pagination
- [workflow-deployment.md](workflow-deployment.md) — Deploy methods, workflowlog

## Working Style
- User prefers concise responses
- Always query dynamically, never reuse hardcoded IDs

## Known Gotchas
- `workflow.simulate` is static analysis only
- MCP response budget truncates large payloads at 50K chars
```

**Account memory index.md** — top-10 gotchas + cross-references:

```markdown
# Account Memory Example

## Top Gotchas (always check these)
1. Store app user actions require `servicepoint` in `modules[]`
2. ORDER::MULTI flexVersion is 4
3. CLI retailer config overrides profile user silently
4. Three workflow directories exist — only the retailer with the space in its name is canonical

## Topic Files
- [learnings.md](learnings.md) — full detail
```

**Account learnings.md** — detailed findings with source:

```markdown
## Entity Patterns
- ORDER::MULTI requires `fulfilmentChoiceRef` on items (discovered 2026-02-15, order creation failed without it)
- CREDIT_MEMO comments queried via `comments(entityType, entityRef)`, NOT a field on the entity

## Deployment
- POM version bump mandatory before every deploy — Fluent caches by version+filename
- Store and OMS app aliases differ from display names; verify `modules[]` before blaming the workflow
```

### When to add memory

- AI discovers unexpected API behavior → account memory
- Deploy fails with a non-obvious error → account memory
- User corrects AI on a platform pattern → global memory or platform knowledge
- AI notices a gotcha that applies to all accounts → global memory

### Memory vs Knowledge decision

| Situation | Goes to |
|-----------|---------|
| "All refs MUST be SCREAMING_SNAKE" (team decision) | **Knowledge** (`partner/naming-conventions.md`) |
| "This account's ORDER::MULTI uses flexVersion 4" (observed) | **Memory** (`accounts/<PROFILE>/memory/`) |
| "Fluent rejects queries with undeclared variables" (platform fact) | **Knowledge** (`platform/`) if validated, **Memory** if just observed once |
| "User prefers concise responses" (working style) | **Memory** (global `MEMORY.md`) |
| "`fc.page` reads retailerId from query variables, not URL" (platform limitation) | **Knowledge** (`platform/mystique-routing.md`) |

**Rule of thumb:** If you'd put it in a team wiki → knowledge. If you'd tell a colleague "heads up, watch out for this" → memory.

---

## 3. Skills — What goes here

**Purpose:** Executable instructions for the AI. How to scaffold a rule, build a workflow, deploy a module.

**Owner:** Skill authors (developers of the fluent-ai-skills package).

**Location:** `content/<group>/skills/<skill-name>/`

### Format

```text
content/dev/skills/fluent-mystique-builder/
├── SKILL.md              # Main instructions (frontmatter + execution flow)
├── TEMPLATES.md          # File templates (optional)
├── API_REFERENCE.md      # Reference material (optional)
└── CRITIQUE_PROTOCOL.md  # Self-critique rules (optional)
```

**Users don't edit skills** — they invoke them with `/fluent-<name>`. Skills read knowledge and memory during their pre-flight phase.

### Skill pre-flight loading chain

When you invoke `/fluent-mystique-builder`:

```
1. `SKILL.md` loads into context
2. Pre-flight reads the packaged platform docs it needs from `knowledge/`
3. It checks `accounts/<PROFILE>/knowledge/` for account-specific overrides
4. It reads `accounts/<PROFILE>/memory/index.md` for account gotchas
5. It reads `accounts/<PROFILE>/feedback/fluent-mystique-builder.jsonl` (last 20 records) when feedback-aware
6. Companion files load if needed (`TEMPLATES.md`, etc.)
7. Skill execution begins with full context
```

---

## Quick Reference

| Question | Answer |
|----------|--------|
| "Where do I put naming rules?" | `accounts/<PROFILE>/knowledge/naming-conventions.md` |
| "Where do platform facts go?" | `knowledge/platform/<topic>.md` + register in `knowledge/index.md` |
| "Where do deploy gotchas go?" | `accounts/<PROFILE>/memory/learnings.md` |
| "Where do working preferences go?" | Global `MEMORY.md` (Working Style section) |
| "Where do client business rules go?" | `accounts/<PROFILE>/knowledge/client/business-rules.md` |
| "How do I override packaged platform knowledge for one account?" | Add the account-specific file under `accounts/<PROFILE>/knowledge/` |
| "How do I make a knowledge file load for a specific skill?" | Add the skill name to `relevant-skills` in frontmatter |
| "Can I delete memory files?" | Yes — AI re-learns from evidence. Knowledge requires human review. |
| "How do I populate knowledge files?" | Run `/fluent-knowledge-init`, or drop docs and say "extract knowledge" |

---

## How to set up from scratch

```
1. /fluent-knowledge-init                     ← wizard asks questions, writes files
2. Drop PDFs/docs → "extract knowledge"       ← AI reads and writes
3. Just work normally                          ← AI captures corrections progressively
```

After 3-5 sessions, knowledge and memory build up organically. Check `accounts/<PROFILE>/knowledge/index.md` to see what's populated for that account.
