@elevasis/sdk 1.20.2 → 1.22.0

package/reference/framework/memory.mdx

@@ -1,326 +1,326 @@
----
-title: Memory System
-description: Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions
-loadWhen: "Working with agent memory or session state"
----
-
-The memory system gives Claude Code a structured knowledge base for your project that survives across sessions. Deployment history, discovered credentials, architectural decisions, and error patterns are all written to `.claude/memory/` as the project evolves -- so the agent never starts from scratch.
-
-The `memory/` directory is gitignored and personal to each developer. The `profile/` subdirectory is created by `/meta init` during first-run setup. All other topics are created by the agent as the project evolves.
-
-## Purpose
-
-Without project memory, the agent starts every session with only the context of the current conversation. It cannot remember that you already deployed yesterday, that a particular credential is configured, or that you encountered and solved a specific TypeScript error last week.
-
-With project memory, the agent loads a root index at session start, sees what has been recorded, and can retrieve detail on demand. Error patterns are matched before diagnosis. Deployment state is available before deploying again. The agent can say "I've seen this before -- here's the fix" instead of repeating the same diagnostic process.
-
-## Architecture
-
-Memory is organized as a hierarchical index tree. Every directory has an `index.md` that maps to its children -- either content files or subdirectories with their own indexes.
-
-**The invariant:** A reader always starts at the root index and drills down. The agent reads `memory/index.md` at session start. It reads individual topic files on demand when the user asks about that topic or the agent is about to perform an action in that domain.
-
-**The scaling rule:** When a content file outgrows a single document, it graduates into a subdirectory:
-
-1. `topic.md` becomes `topic/index.md` + sub-files
-2. The parent index updates its link from `topic.md` to `topic/index.md`
-3. The new sub-index maps to the sub-files
-
-This pattern is recursive. Subdirectories can split further as needed. The agent applies its own judgment about when a file has grown past usefulness as a single document.
-
-### Starting Structure
-
-After `/meta init` and a first deployment, the structure looks like this:
-
-```
-.claude/memory/
-├── index.md                    # Root index -- read at session start
-├── profile/                    # Developer profile (created by /meta init)
-│   ├── index.md                # Profile summary with links to sub-files
-│   ├── identity.md             # Organization, industry, goals, integrations
-│   ├── skills.md               # Skill dimensions and Growth Log
-│   └── preferences.md          # Verbosity, guidance style, interaction patterns
-├── deployment-state.md         # Deploy IDs, resource inventory, org info
-├── environment.md              # Credentials, API keys, env vars
-├── decisions.md                # Architectural decisions and patterns
-└── errors/                     # Subdirectory -- multiple categories
-    ├── index.md                # Error category summary with counts
-    ├── deploy.md               # Deployment error patterns
-    ├── runtime.md              # Runtime execution error patterns
-    └── typescript.md           # Type and build error patterns
-```
-
-Profile tracking starts as a subdirectory because it has natural sub-topics from day one (identity, skills, preferences). Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files.
-
-### Grown Structure
-
-As a project matures, other topics may split:
-
-```
-.claude/memory/
-├── index.md
-├── environment.md
-├── decisions.md
-├── deployment-state/           # Grew large enough to split
-│   ├── index.md
-│   ├── resources.md
-│   └── history.md
-└── errors/
-    ├── index.md
-    ├── deploy.md
-    ├── typescript.md
-    └── runtime/                # Runtime errors grew further
-        ├── index.md
-        ├── lead-scorer.md
-        └── email-sender.md
-```
-
-## Memory Topics
-
-### Developer Profile
-
-The `profile/` directory stores the developer's personal context -- organization details, skill levels, goals, and interaction preferences. It is created during `/meta init` guided setup and is the first thing the root index links to.
-
-```
-.claude/memory/profile/
-├── index.md          # Profile summary with links to sub-files
-├── identity.md       # Organization, industry, goals, integrations
-├── skills.md         # Skill dimensions and Growth Log
-└── preferences.md    # Verbosity, guidance style, interaction patterns
-```
-
-**`identity.md`** records the organization name, industry, size, project goals, and known tool integrations. Example:
-
-```markdown
-# Identity
-
-| Field | Value |
-| --- | --- |
-| Organization | Acme Corp |
-| Industry | E-commerce |
-| Size | 10-50 |
-
-## Project Goals
-
-- Automate lead scoring from Attio CRM
-- Send follow-up emails via Resend
-- Weekly pipeline reports
-
-## Known Integrations
-
-- Attio (CRM)
-- Resend (email)
-- Google Sheets (reporting)
-```
-
-**`skills.md`** stores four skill dimensions as structured values so the Adaptive Guidance rules in [Interaction Guidance](interaction-guidance.mdx) can apply them consistently. It also tracks a Growth Log so the agent can detect when a level upgrade is warranted. Example:
-
-```markdown
-# Skills
-
-| Dimension | Level | Since |
-| --- | --- | --- |
-| platformNavigation | oriented | 2026-02-25 |
-| apiIntegration | basic | 2026-02-25 |
-| automation | low-code | 2026-02-25 |
-| domainExpertise | high | 2026-02-25 |
-
-## Growth Log
-
-| Date | Observation | Dimension | Change |
-| --- | --- | --- | --- |
-| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
-```
-
-Valid levels per dimension:
-
-- `platformNavigation`: none / oriented / comfortable
-- `apiIntegration`: none / basic / proficient
-- `automation`: none / low-code / custom
-- `domainExpertise`: high / low
-
-**`preferences.md`** stores verbosity and proactive guidance settings. Example:
-
-```markdown
-# Preferences
-
-| Setting | Value |
-| --- | --- |
-| Verbosity | detailed |
-| Proactive guidance | yes |
-```
-
-### Root Index
-
-`memory/index.md` is the only file read at session start. It lists all topics with their last-updated dates, giving the agent enough context to know what has been recorded without loading any detail.
-
-```markdown
-# Project Memory
-
-Agent-maintained cross-session knowledge base. Updated automatically.
-
-| Entry | Topic | Last Updated |
-| --- | --- | --- |
-| [profile/](profile/index.md) | Developer profile (skills, identity, preferences) | 2026-02-25 |
-| [deployment-state.md](deployment-state.md) | Deploy history, resource inventory, org info | 2026-02-25 |
-| [environment.md](environment.md) | Credentials, API keys, env vars | 2026-02-25 |
-| [decisions.md](decisions.md) | Architectural decisions and patterns | 2026-02-26 |
-| [errors/](errors/index.md) | Error patterns by category | 2026-02-26 |
-```
-
-Subdirectory entries link to their `index.md` rather than the directory itself.
-
-### Deployment State
-
-`deployment-state.md` tracks the most recent deploy and resource inventory. The agent updates it after every successful deployment.
-
-```markdown
-# Deployment State
-
-## Latest Deploy
-
-| Field | Value |
-| --- | --- |
-| Date | 2026-02-26 |
-| Deploy ID | dep_abc123 |
-| Resource count | 2 |
-| Organization | acme-corp |
-
-## Resources
-
-- `echo` (workflow, dev) -- echoes input, starter resource
-- `lead-scorer` (workflow, prod) -- scores leads from Attio
-
-## Deploy History
-
-| Date | Deploy ID | Resources | Status |
-| --- | --- | --- | --- |
-| 2026-02-26 | dep_abc123 | 2 | success |
-| 2026-02-25 | dep_xyz789 | 1 | success |
-```
-
-### Environment
-
-`environment.md` records discovered credentials and environment variable status. The agent updates it when credentials are confirmed via the command center or deployment output.
-
-### Decisions
-
-`decisions.md` captures architectural choices as a table: which tools were chosen, what patterns were established, and why. The agent adds a row when the user makes a significant decision during development.
-
-## Error Tracking
-
-Error tracking is the first memory topic to outgrow a flat file. It starts as a subdirectory with one file per error category.
-
-### Error Index
-
-`errors/index.md` provides a high-level summary of known error patterns by category. The agent reads this file (via the root index) at session start.
-
-```markdown
-# Error Patterns
-
-Error pattern tracking by category. Updated when errors are diagnosed and resolved.
-
-| Entry | Category | Patterns | Total Occurrences | Last Seen |
-| --- | --- | --- | --- | --- |
-| [deploy.md](deploy.md) | Deployment | 2 | 3 | 2026-02-26 |
-| [runtime.md](runtime.md) | Runtime | 1 | 1 | 2026-02-26 |
-| [typescript.md](typescript.md) | TypeScript | 1 | 2 | 2026-02-25 |
-```
-
-- **Patterns** -- count of unique error patterns in the category file
-- **Total Occurrences** -- sum of all occurrences across patterns
-- **Last Seen** -- most recent date any error in this category was seen
-
-### Category Files
-
-Each category file is a table of known error patterns with resolutions:
-
-```markdown
-# Deploy Errors
-
-| Last Seen | Error | Resolution | Occurrences |
-| --- | --- | --- | --- |
-| 2026-02-25 | `ELEVASIS_PLATFORM_KEY not set` | Added key to `.env` | 2 |
-| 2026-02-26 | `Schema validation: missing outputSchema` | Added Zod output schema to workflow | 1 |
-```
-
-Runtime errors include the resource name since the same error in different resources may have different causes:
-
-```markdown
-# Runtime Errors
-
-| Last Seen | Resource | Error | Resolution | Occurrences |
-| --- | --- | --- | --- | --- |
-| 2026-02-26 | lead-scorer | `PlatformToolError: credential not found` | Set credential via `elevasis-sdk env set` | 1 |
-```
-
-### Error Resolution Flow
-
-When the agent encounters an error, it follows this sequence:
-
-1. Checks `memory/errors/index.md` (already loaded via root index) for a matching category
-2. If the relevant category has known patterns, reads the category file
-3. If a match exists, applies the known resolution immediately -- "I've seen this before, here's the fix"
-4. If no match exists, diagnoses normally, then logs the new pattern
-
-When the agent logs a resolved error:
-
-1. Reads the relevant category file (e.g., `memory/errors/deploy.md`)
-2. If the pattern already exists, increments `Occurrences` and updates `Last Seen`
-3. If it is a new pattern, adds a new row
-4. Updates the error index: recalculates `Patterns`, `Total Occurrences`, and `Last Seen`
-5. If the category file does not exist yet, creates it and adds a row to the error index
-
-## Scaling Rule
-
-When a file has grown past usefulness as a single document -- too many rows to scan, too many unrelated concerns, or too much context to load for a targeted lookup -- split it into a subdirectory.
-
-**Before split:**
-
-```
-memory/
-├── index.md
-└── deployment-state.md         # entry: deployment-state.md
-```
-
-**After split:**
-
-```
-memory/
-├── index.md                    # entry updated: deployment-state/ -> deployment-state/index.md
-└── deployment-state/
-    ├── index.md
-    ├── resources.md
-    └── history.md
-```
-
-The parent index link changes from `deployment-state.md` to `deployment-state/index.md`. The new sub-index maps to the sub-files. The agent applies this pattern at every depth level.
-
-## Maintenance
-
-### Pruning
-
-Keep content useful, not exhaustive:
-
-- Keep the most recent ~20 entries in tables that grow over time (deploy history, error patterns)
-- Drop patterns that have not recurred in 30 or more days unless the resolution was non-obvious
-- Summarize if patterns are worth preserving but detail is not
-
-### Index Hygiene
-
-- If a file exists but is not in its parent index, add it
-- If an index references a missing file, remove the row
-
-The agent self-heals on read. Index hygiene is applied as part of normal session operation.
-
-### Promotion
-
-If an error pattern recurs 3 or more times, promote it to a rule in the `CLAUDE.md` Rules section. Rules prevent errors rather than diagnosing them.
-
-## Relationship to Claude Code Auto-Memory
-
-Claude Code's auto-memory (`MEMORY.md`) and project memory (`.claude/memory/`) are complementary -- both should be active. Auto-memory captures organic discoveries; project memory captures structured project state that `CLAUDE.md` explicitly instructs the agent to record.
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Memory System
+description: Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions
+loadWhen: "Working with agent memory or session state"
+---
+
+The memory system gives Claude Code a structured knowledge base for your project that survives across sessions. Deployment history, discovered credentials, architectural decisions, and error patterns are all written to `.claude/memory/` as the project evolves -- so the agent never starts from scratch.
+
+The `memory/` directory is gitignored and personal to each developer. The `profile/` subdirectory is created by `/meta init` during first-run setup. All other topics are created by the agent as the project evolves.
+
+## Purpose
+
+Without project memory, the agent starts every session with only the context of the current conversation. It cannot remember that you already deployed yesterday, that a particular credential is configured, or that you encountered and solved a specific TypeScript error last week.
+
+With project memory, the agent loads a root index at session start, sees what has been recorded, and can retrieve detail on demand. Error patterns are matched before diagnosis. Deployment state is available before deploying again. The agent can say "I've seen this before -- here's the fix" instead of repeating the same diagnostic process.
+
+## Architecture
+
+Memory is organized as a hierarchical index tree. Every directory has an `index.md` that maps to its children -- either content files or subdirectories with their own indexes.
+
+**The invariant:** A reader always starts at the root index and drills down. The agent reads `memory/index.md` at session start. It reads individual topic files on demand when the user asks about that topic or the agent is about to perform an action in that domain.
+
+**The scaling rule:** When a content file outgrows a single document, it graduates into a subdirectory:
+
+1. `topic.md` becomes `topic/index.md` + sub-files
+2. The parent index updates its link from `topic.md` to `topic/index.md`
+3. The new sub-index maps to the sub-files
+
+This pattern is recursive. Subdirectories can split further as needed. The agent applies its own judgment about when a file has grown past usefulness as a single document.
+
+### Starting Structure
+
+After `/meta init` and a first deployment, the structure looks like this:
+
+```
+.claude/memory/
+├── index.md                    # Root index -- read at session start
+├── profile/                    # Developer profile (created by /meta init)
+│   ├── index.md                # Profile summary with links to sub-files
+│   ├── identity.md             # Organization, industry, goals, integrations
+│   ├── skills.md               # Skill dimensions and Growth Log
+│   └── preferences.md          # Verbosity, guidance style, interaction patterns
+├── deployment-state.md         # Deploy IDs, resource inventory, org info
+├── environment.md              # Credentials, API keys, env vars
+├── decisions.md                # Architectural decisions and patterns
+└── errors/                     # Subdirectory -- multiple categories
+    ├── index.md                # Error category summary with counts
+    ├── deploy.md               # Deployment error patterns
+    ├── runtime.md              # Runtime execution error patterns
+    └── typescript.md           # Type and build error patterns
+```
+
+Profile tracking starts as a subdirectory because it has natural sub-topics from day one (identity, skills, preferences). Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files.
+
+### Grown Structure
+
+As a project matures, other topics may split:
+
+```
+.claude/memory/
+├── index.md
+├── environment.md
+├── decisions.md
+├── deployment-state/           # Grew large enough to split
+│   ├── index.md
+│   ├── resources.md
+│   └── history.md
+└── errors/
+    ├── index.md
+    ├── deploy.md
+    ├── typescript.md
+    └── runtime/                # Runtime errors grew further
+        ├── index.md
+        ├── lead-scorer.md
+        └── email-sender.md
+```
+
+## Memory Topics
+
+### Developer Profile
+
+The `profile/` directory stores the developer's personal context -- organization details, skill levels, goals, and interaction preferences. It is created during `/meta init` guided setup and is the first thing the root index links to.
+
+```
+.claude/memory/profile/
+├── index.md          # Profile summary with links to sub-files
+├── identity.md       # Organization, industry, goals, integrations
+├── skills.md         # Skill dimensions and Growth Log
+└── preferences.md    # Verbosity, guidance style, interaction patterns
+```
+
+**`identity.md`** records the organization name, industry, size, project goals, and known tool integrations. Example:
+
+```markdown
+# Identity
+
+| Field | Value |
+| --- | --- |
+| Organization | Acme Corp |
+| Industry | E-commerce |
+| Size | 10-50 |
+
+## Project Goals
+
+- Automate lead scoring from Attio CRM
+- Send follow-up emails via Resend
+- Weekly pipeline reports
+
+## Known Integrations
+
+- Attio (CRM)
+- Resend (email)
+- Google Sheets (reporting)
+```
+
+**`skills.md`** stores four skill dimensions as structured values so the Adaptive Guidance rules in [Interaction Guidance](interaction-guidance.mdx) can apply them consistently. It also tracks a Growth Log so the agent can detect when a level upgrade is warranted. Example:
+
+```markdown
+# Skills
+
+| Dimension | Level | Since |
+| --- | --- | --- |
+| platformNavigation | oriented | 2026-02-25 |
+| apiIntegration | basic | 2026-02-25 |
+| automation | low-code | 2026-02-25 |
+| domainExpertise | high | 2026-02-25 |
+
+## Growth Log
+
+| Date | Observation | Dimension | Change |
+| --- | --- | --- | --- |
+| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
+```
+
+Valid levels per dimension:
+
+- `platformNavigation`: none / oriented / comfortable
+- `apiIntegration`: none / basic / proficient
+- `automation`: none / low-code / custom
+- `domainExpertise`: high / low
+
+**`preferences.md`** stores verbosity and proactive guidance settings. Example:
+
+```markdown
+# Preferences
+
+| Setting | Value |
+| --- | --- |
+| Verbosity | detailed |
+| Proactive guidance | yes |
+```
+
+### Root Index
+
+`memory/index.md` is the only file read at session start. It lists all topics with their last-updated dates, giving the agent enough context to know what has been recorded without loading any detail.
+
+```markdown
+# Project Memory
+
+Agent-maintained cross-session knowledge base. Updated automatically.
+
+| Entry | Topic | Last Updated |
+| --- | --- | --- |
+| [profile/](profile/index.md) | Developer profile (skills, identity, preferences) | 2026-02-25 |
+| [deployment-state.md](deployment-state.md) | Deploy history, resource inventory, org info | 2026-02-25 |
+| [environment.md](environment.md) | Credentials, API keys, env vars | 2026-02-25 |
+| [decisions.md](decisions.md) | Architectural decisions and patterns | 2026-02-26 |
+| [errors/](errors/index.md) | Error patterns by category | 2026-02-26 |
+```
+
+Subdirectory entries link to their `index.md` rather than the directory itself.
+
+### Deployment State
+
+`deployment-state.md` tracks the most recent deploy and resource inventory. The agent updates it after every successful deployment.
+
+```markdown
+# Deployment State
+
+## Latest Deploy
+
+| Field | Value |
+| --- | --- |
+| Date | 2026-02-26 |
+| Deploy ID | dep_abc123 |
+| Resource count | 2 |
+| Organization | acme-corp |
+
+## Resources
+
+- `echo` (workflow, dev) -- echoes input, starter resource
+- `lead-scorer` (workflow, prod) -- scores leads from Attio
+
+## Deploy History
+
+| Date | Deploy ID | Resources | Status |
+| --- | --- | --- | --- |
+| 2026-02-26 | dep_abc123 | 2 | success |
+| 2026-02-25 | dep_xyz789 | 1 | success |
+```
+
+### Environment
+
+`environment.md` records discovered credentials and environment variable status. The agent updates it when credentials are confirmed via the command center or deployment output.
+
+### Decisions
+
+`decisions.md` captures architectural choices as a table: which tools were chosen, what patterns were established, and why. The agent adds a row when the user makes a significant decision during development.
+
+## Error Tracking
+
+Error tracking is the first memory topic to outgrow a flat file. It starts as a subdirectory with one file per error category.
+
+### Error Index
+
+`errors/index.md` provides a high-level summary of known error patterns by category. The agent reads this file (via the root index) at session start.
+
+```markdown
+# Error Patterns
+
+Error pattern tracking by category. Updated when errors are diagnosed and resolved.
+
+| Entry | Category | Patterns | Total Occurrences | Last Seen |
+| --- | --- | --- | --- | --- |
+| [deploy.md](deploy.md) | Deployment | 2 | 3 | 2026-02-26 |
+| [runtime.md](runtime.md) | Runtime | 1 | 1 | 2026-02-26 |
+| [typescript.md](typescript.md) | TypeScript | 1 | 2 | 2026-02-25 |
+```
+
+- **Patterns** -- count of unique error patterns in the category file
+- **Total Occurrences** -- sum of all occurrences across patterns
+- **Last Seen** -- most recent date any error in this category was seen
+
+### Category Files
+
+Each category file is a table of known error patterns with resolutions:
+
+```markdown
+# Deploy Errors
+
+| Last Seen | Error | Resolution | Occurrences |
+| --- | --- | --- | --- |
+| 2026-02-25 | `ELEVASIS_PLATFORM_KEY not set` | Added key to `.env` | 2 |
+| 2026-02-26 | `Schema validation: missing outputSchema` | Added Zod output schema to workflow | 1 |
+```
+
+Runtime errors include the resource name since the same error in different resources may have different causes:
+
+```markdown
+# Runtime Errors
+
+| Last Seen | Resource | Error | Resolution | Occurrences |
+| --- | --- | --- | --- | --- |
+| 2026-02-26 | lead-scorer | `PlatformToolError: credential not found` | Set credential via `elevasis-sdk env set` | 1 |
+```
+
+### Error Resolution Flow
+
+When the agent encounters an error, it follows this sequence:
+
+1. Checks `memory/errors/index.md` (already loaded via root index) for a matching category
+2. If the relevant category has known patterns, reads the category file
+3. If a match exists, applies the known resolution immediately -- "I've seen this before, here's the fix"
+4. If no match exists, diagnoses normally, then logs the new pattern
+
+When the agent logs a resolved error:
+
+1. Reads the relevant category file (e.g., `memory/errors/deploy.md`)
+2. If the pattern already exists, increments `Occurrences` and updates `Last Seen`
+3. If it is a new pattern, adds a new row
+4. Updates the error index: recalculates `Patterns`, `Total Occurrences`, and `Last Seen`
+5. If the category file does not exist yet, creates it and adds a row to the error index
+
+## Scaling Rule
+
+When a file has grown past usefulness as a single document -- too many rows to scan, too many unrelated concerns, or too much context to load for a targeted lookup -- split it into a subdirectory.
+
+**Before split:**
+
+```
+memory/
+├── index.md
+└── deployment-state.md         # entry: deployment-state.md
+```
+
+**After split:**
+
+```
+memory/
+├── index.md                    # entry updated: deployment-state/ -> deployment-state/index.md
+└── deployment-state/
+    ├── index.md
+    ├── resources.md
+    └── history.md
+```
+
+The parent index link changes from `deployment-state.md` to `deployment-state/index.md`. The new sub-index maps to the sub-files. The agent applies this pattern at every depth level.
+
+## Maintenance
+
+### Pruning
+
+Keep content useful, not exhaustive:
+
+- Keep the most recent ~20 entries in tables that grow over time (deploy history, error patterns)
+- Drop patterns that have not recurred in 30 or more days unless the resolution was non-obvious
+- Summarize if patterns are worth preserving but detail is not
+
+### Index Hygiene
+
+- If a file exists but is not in its parent index, add it
+- If an index references a missing file, remove the row
+
+The agent self-heals on read. Index hygiene is applied as part of normal session operation.
+
+### Promotion
+
+If an error pattern recurs 3 or more times, promote it to a rule in the `CLAUDE.md` Rules section. Rules prevent errors rather than diagnosing them.
+
+## Relationship to Claude Code Auto-Memory
+
+Claude Code's auto-memory (`MEMORY.md`) and project memory (`.claude/memory/`) are complementary -- both should be active. Auto-memory captures organic discoveries; project memory captures structured project state that `CLAUDE.md` explicitly instructs the agent to record.
+
+---
+
+**Last Updated:** 2026-02-25