Memory Commands

`saedra memory state view`

Display the current architecture state of the linked project.

$ saedra memory state view
Using project: my-infra (from .saedra)

  Architecture State — my-infra
  Version: 2026-03-04

  Summary:
    Monorepo with three packages: cli, db-queries, project-service.

  Core Principles:
    - Single source of truth in Supabase
    - CLI is stateless except for ~/.saedra/config.json

  Critical Paths:
    - auth token → all API calls

  Constraints:
    - No direct DB access from CLI

  Active Decisions:
    - DEC-2026-03-04-document-type

If no state exists yet, it prompts to create one with saedra memory state update.

`saedra memory state update`

Interactively fill in or overwrite the architecture state. Creates the record if none exists, or updates it in place.

$ saedra memory state update
Using project: my-infra (from .saedra)

  Architecture State — Update

? Summary (describe the current architecture): Monorepo with three packages...
  Core principles: (enter each item, empty line to finish)
  [1] Single source of truth in Supabase
  [2]
  Critical paths: (enter each item, empty line to finish)
  [1] auth token → all API calls
  [2]
  Constraints: (enter each item, empty line to finish)
  [1] No direct DB access from CLI
  [2]
  Active decision IDs (e.g. DEC-2026-03-04-auth): (enter each item, empty line to finish)
  [1] DEC-2026-03-04-document-type
  [2]
? Save this architecture state? (Y/n)

Architecture state updated successfully.

`saedra memory state update --ai`

Generates the architecture state automatically using AI. Fetches all active decisions and the last 10 change events, sends them to Claude, and proposes a compressed ArchitectureState for review before saving.

Requires AI to be configured first via saedra ai setup.

$ saedra memory state update --ai
Using project: my-infra (from .saedra)

  AI Architecture Compression

  Fetching project memory...
  Found 2 active decision(s) and 5 change event(s).
  Sending to AI for compression...

  Thinking...............................................

  Proposed Architecture State:

  Summary:
    Monorepo (Turborepo + pnpm) combining auth, project management, AI via AWS Bedrock...

  Core Principles:
    - TypeScript strict across all packages
    - ...

  Critical Paths:
    - apps/api → project-service → db-queries → db-connector → Supabase
    - ...

  Constraints:
    - Node.js >= 18 required
    - ...

  Active Decisions:
    - DEC-2026-03-09-use-supabase-as-primary-databa

? Save this as the new architecture state? (Y/n)

Architecture state updated successfully.

The AI reads the current state as context and evolves it — preserving what is still accurate and incorporating what changed.

`saedra memory decision add`

Record a new architectural decision. Generates an ID in the format DEC-YYYY-MM-DD-slug and stores it as a structured document of type=decision.

$ saedra memory decision add
Using project: my-infra (from .saedra)

  New Decision

? Title: Use document type field for memory
? Context (why was this decision needed?): Need to differentiate free docs from memory records.
? Decision (what was decided?): Add a type column to documents table.
? Risk level: low
  Impact: (enter each item, empty line to finish)
  [1] All document queries must filter by type
  [2]
  Affected modules/domains: (enter each item, empty line to finish)
  [1] db-queries
  [2] project-service
  [3]
  Constraints introduced: (enter each item, empty line to finish)
  [1]
? Supersedes (decision ID, leave empty if none):
? Save decision "DEC-2026-03-04-use-document-type-fie"? (Y/n)

Decision "DEC-2026-03-04-use-document-type-fie" saved successfully.

`saedra memory decision list`

List all architectural decisions recorded for the project.

$ saedra memory decision list
Using project: my-infra (from .saedra)

  Decisions — my-infra

  DEC-2026-03-04-use-document-type-fie
    Title:    Use document type field for memory
    Status:   active  Risk: [LOW]
    Decision: Add a type column to documents table.
    Affects:  db-queries, project-service

`saedra memory change log`

Log a change event interactively. Generates an ID in the format CHG-YYYY-MM-DD-slug and stores it as a structured document of type=change.

$ saedra memory change log
Using project: my-infra (from .saedra)

  New Change Event

? Summary: Add memory change commands to CLI
  Files changed: (enter each item, empty line to finish)
  [1] packages/cli/src/commands/memory.ts
  [2] packages/cli/src/index.ts
  [3]
? Architectural impact: Extends memory subcommand with change tracking
? Risk assessment: low — additive only
  Related decision IDs (e.g. DEC-2026-03-04-auth): (enter each item, empty line to finish)
  [1] DEC-2026-03-04-use-document-type-fie
  [2]
? Save change "CHG-2026-03-05-add-memory-change-comm"? (Y/n)

Change event "CHG-2026-03-05-add-memory-change-comm" saved successfully.

`saedra memory change log --from-git`

Same as change log but pre-fills summary from the last git commit message and files_changed from git diff --name-only HEAD~1 HEAD. Prompts for confirmation before using the pre-filled values.

$ saedra memory change log --from-git
Using project: my-infra (from .saedra)

  New Change Event

? Summary: [pre-filled: Add memory change commands to CLI]
  Files changed (pre-filled from git):
    packages/cli/src/commands/memory.ts
    packages/cli/src/index.ts
? Use these files? (Y/n)
? Architectural impact: Extends memory subcommand with change tracking
? Risk assessment: low — additive only
  Related decision IDs ...: (enter each item, empty line to finish)
  [1]
? Save change "CHG-2026-03-05-add-memory-change-comm"? (Y/n)

Change event "CHG-2026-03-05-add-memory-change-comm" saved successfully.

Must be run inside a git repository with at least one commit.

`saedra memory change log --from-git --no-prompt`

Fully automatic mode. Uses the commit message as summary and git diff as file list, skips all interactive prompts, and saves the change event directly. This is the mode used by the git hook installed via saedra init --with-hooks.

$ saedra memory change log --from-git --no-prompt
Using project: my-infra (from .saedra)
Change event "CHG-2026-03-06-add-git-hook-support" saved.

`saedra memory change list`

List all change events for the project in chronological order.

$ saedra memory change list
Using project: my-infra (from .saedra)

  Change Timeline — my-infra

  CHG-2026-03-05-add-memory-change-comm
    Summary: Add memory change commands to CLI
    Impact:  Extends memory subcommand with change tracking
    Risk:    low — additive only
    Files:   packages/cli/src/commands/memory.ts, packages/cli/src/index.ts
    Decisions: DEC-2026-03-04-use-document-type-fie

`saedra memory change analyze [id]`

Analyze the architectural impact of a change event using AI. By default, analyzes the most recent change event. Optionally accepts a change ID to analyze a specific event.

Loads the full project context (architecture state, active decisions, violation rules) alongside the change event and sends everything to the configured AI, streaming a structured impact analysis.

Requires AI to be configured first via saedra ai setup.

$ saedra memory change analyze
Using project: my-infra (from .saedra)

  AI Impact Analysis

  Analyzing: CHG-2026-03-06-add-git-hook-support
  Summary:   Add git hook support
  Files:     packages/cli/src/commands/context.ts, packages/cli/src/index.ts

  ──────────────────────────────────────────────────
  ## Impact Summary
  This change introduces automatic change event tracking via a post-commit git hook,
  extending the memory system's capture surface without modifying existing schemas or flows.
  It is a purely additive feature with no breaking changes.

  ## Affected Decisions
  - **DEC-2026-03-04-use-document-type-fie** — reinforced: change events continue to be
    stored as `type=change` documents, consistent with the document-type strategy.

  ## Rule Compliance
  No violation rules are touched by this change. The hook only calls an existing CLI
  command (`saedra memory change log --from-git --no-prompt`) — no new imports or
  structural patterns introduced.

  ## Risk Assessment
  **Low.** The change is additive and isolated to the CLI init flow. No shared packages
  or API routes are modified.

  ## Overlooked Concerns
  The recorded impact was empty. Worth noting: if `.git/hooks/post-commit` already exists
  on a teammate's machine, the hook is silently skipped — this should be documented.
  ──────────────────────────────────────────────────

To analyze a specific change event by ID:

$ saedra memory change analyze CHG-2026-03-04-add-type-column
Using project: my-infra (from .saedra)

  AI Impact Analysis

  Analyzing: CHG-2026-03-04-add-type-column
  ...

`saedra memory rule add`

Add a new architectural violation rule. Generates an ID in the format RULE-YYYY-MM-DD-slug and stores it as a structured document of type=rule. Rules define constraints that must not be broken — they are the ground truth used by saedra review.

$ saedra memory rule add
Using project: my-infra (from .saedra)

  New Violation Rule

? Description (what must not happen?): Controllers cannot import db-connector directly
? Severity: > high
              medium
              low
? Related decision (ID, leave empty if none): DEC-2026-03-04-use-document-type-fie

? Save rule "RULE-2026-03-23-controllers-cannot-impor"? (Y/n)

Rule "RULE-2026-03-23-controllers-cannot-impor" saved successfully.

`saedra memory rule list`

List all violation rules recorded for the project.

$ saedra memory rule list
Using project: my-infra (from .saedra)

  Violation Rules — my-infra

  RULE-2026-03-23-controllers-cannot-impor  [HIGH]
    Constraint: Controllers cannot import db-connector directly
    Decision:   DEC-2026-03-04-use-document-type-fie

`saedra memory compress`

Snapshot the full architecture context to a local .saedra-context.json file. Fetches state, active decisions, the 10 most recent change events, and all violation rules from the server and writes them to disk.

Useful for offline access, CI pipelines, and fast context injection without requiring network access.

$ saedra memory compress
Using project: my-infra (from .saedra)

  Compressing architecture context — my-infra

  Fetching architecture state...    ✓
  Fetching active decisions...      ✓ (2)
  Fetching recent changes...        ✓ (5)
  Fetching violation rules...       ✓ (1)

  ✓  Snapshot saved to .saedra-context.json
     State:      1 architecture state
     Decisions:  2 active decisions
     Changes:    5 recent changes
     Rules:      1 violation rule
     Generated:  2026-04-21T14:32:00Z

The generated file includes a generated_at timestamp so you always know when the snapshot was taken:

{
  "project": "my-infra",
  "project_id": "798593a3-...",
  "generated_at": "2026-04-13T00:00:00Z",
  "state": { ... },
  "decisions": [ ... ],
  "changes": [ ... ],
  "rules": [ ... ]
}

.saedra-context.json is added to .gitignore automatically — it is a local snapshot, not a committed artifact.

Automatic update via git hook: when installed with saedra init --with-hooks, the post-commit hook runs saedra memory compress after every commit, keeping the snapshot in sync with the latest change event automatically.

Memory Commands

On this page