# Memory Bank Init

> Create or refresh workspace memory-bank/ (MVP contract + read-only inventory). Path follows STORAGE manifest. No app code; no uv/specify. Use when invoking /memory-bank-init or Orchestrated Delivery Step 0 / Step N needs create/refresh/refresh-light.

- Skill: `tibursocampos/memory-bank-init` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add tibursocampos/memory-bank-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tibursocampos/memory-bank-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tibursocampos (https://skillmd.com/u/tibursocampos)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tibursocampos/memory-bank-init

---


## STOP - Read before ANY tool call

1. Read `{{GUARDRAILS_PATH}}`
2. Read `_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. After create **or** refresh / refresh-light completes: **STOP** - handoff only (do not start O1/O2/O3 in this skill)
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**

### Step -1 - Gate check (report in chat before continuing)

```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] MEMORY-BANK.md read
[ ] STORAGE.md read (bank_root resolution)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```

---

# Skill: memory-bank-init

Credits: memory-bank ideas inspired in part by [github/spec-kit](https://github.com/github/spec-kit); this skill does **not** run Spec Kit / uv / specify. See `docs/CREDITS.md`.

## Trigger

Invoke when the user asks for: `/memory-bank-init`, `init memory bank`, `refresh memory bank`, or when Orchestrated Delivery Step 0 / Step N (`MEMORY-BANK.md`) requires create/refresh/refresh-light.

Optional args: `create` (default if missing), `refresh`, `refresh-light`, path to consumer repo.

## Outcome

Under the resolved **`bank_root`** (`STORAGE.md` + `MEMORY-BANK.md`):

```text
memory-bank/
  project-context.md
  tech-stack.json
  architecture.md
  domain-knowledge.md
  conventions.md
  known-risks.md
  database-schema.md      # phase 2 — when relevant / BLOCKING
  api-contracts.md        # phase 2 — when relevant / BLOCKING
  component-catalog.md    # phase 2 — when relevant / BLOCKING
  .inventory/
    sources.json
    gaps.md
    refresh-history.jsonl
```

MVP files are always required. Phase 2 files: write from templates when Prior/cited content or inventory signals make them relevant. If Prior already has DDL, OpenAPI, or a UI component map, the matching file is **BLOCKING** (or promote immediately) — empty `gaps.md` phase 2 is not “optional forever” (`MEMORY-BANK.md`).

| `storage_mode` | `bank_root` |
|----------------|-------------|
| **repository** | `$Cwd/memory-bank/` |
| **global** | `<classic.path>/memory-bank/` |

**Does not** write application code. **Does not** install Python/uv/specify. **Does not** place the bank under `features/NNN-slug/`. **Commit bank when product knowledge; never commit secrets.** Do **not** add `/memory-bank/` as a required SDD gitignore entry.

## Lazy-load

| When | Path |
|------|------|
| Command playbook (step discovery after gates) | `{{TOOLKIT_ROOT}}/skills/memory-bank-init/references/command.md` |
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Lite cap** |
| Narrative compact (optional) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/COMPACT.md` — CONTINUITY / known-risks only; requires user **sim** |
| Invocation contexts (`direct` vs `orchestrated`, `IC-DIRECT-ORCHESTRATED`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/INVOCATION-CONTEXTS.md` |
| Gate policies, stale, versioning, Step N | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/MEMORY-BANK.md` |
| Manifest, `bank_root`, `.gitignore` | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md` |
| Templates | `{{TOOLKIT_ROOT}}/skills/_shared/templates/memory-bank/` |
| Inventory script | toolkit `scripts/inventory/Invoke-MemoryBankInventory.ps1` (or synced copy if present) |
| Reference index (routing only) | `skills/memory-bank-init/reference.md` |
| Process step detail (lazy) | `skills/memory-bank-init/references/<section>.md` |
| Context pressure | `{{TOOLKIT_ROOT}}/rules/context-management.mdc` |
| Language surfaces (chat vs spawn) | `{{TOOLKIT_ROOT}}/skills/_shared/agents/LANGUAGE.md` |

**Never by default:** do not preload `references/command.md` before Step -1 gates; do not preload all `references/*.md`, full PIPELINE/ROSTER packs, or all memory-bank templates at once. Contract first (`MEMORY-BANK` + `STORAGE`); after gates load `references/command.md` for step discovery; load **one** `references/<section>.md` per Process step (`SKILL-REFERENCE-RETRIEVAL.md`).

## Process

After gates: **Read `references/command.md`** for ordered step discovery (prefer over dumping this Process into prompts). Then load `references/<section>.md` for procedural tables — **not** full `reference.md`.

### Step -1b - Caveman Mode (Lite cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full" }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Lite** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.

### 1. Gate check

Report Step -1 checklist. Load `MEMORY-BANK.md` and `STORAGE.md`. **STOP** if unchecked.
Resolve `invocation_context` per `INVOCATION-CONTEXTS.md` (`IC-DIRECT-ORCHESTRATED`): default `direct` unless Step 0 / Step N parent marks `orchestrated`. Apply the matching observable table.

### 2. Resolve target

1. Confirm **consumer** repo (not toolkit unless explicit).
2. Resolve storage with `$Workflow = classic` (`STORAGE.md`).
3. `bank_root`:
   - **repository** -> `$Cwd/memory-bank/`
   - **global** -> `<classic.path>/memory-bank/`
4. Never under `features/`.
5. Mode:
   - **create** if bank missing/incomplete
   - **refresh** if user asked or Step 0 marked stale
   - **refresh-light** if user asked or O3 Step N after code changes

### 3. Gitignore (repository only)

If `storage_mode` is **repository**: ensure SDD `.gitignore` block per `STORAGE.md` (**`/features/`** and safety-net patterns only — **do not** add or require `/memory-bank/`) **before** the first bank Write. Commit bank when product knowledge; never commit secrets.

If **global**: do **not** edit or suggest SDD patterns in the consumer `.gitignore`.

### 4. Confirm before write

Show (pt-BR): mode, full `bank_root`, files to create/update. Ask:

`Posso gravar o memory-bank em '{path}'? (sim / ajustar / cancelar)`

Write only after **sim**.

### 5. Inventory (read-only scan of consumer)

Prefer script (always scan `$Cwd`; write inventory under `bank_root`):

```powershell
# create (default)
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory

# refresh / refresh-light — pass -Action to match mode for refresh-history.jsonl
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory -Action refresh
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory -Action refresh-light
```

Output in `<bank_root>/.inventory/sources.json`:

| Field | Meaning |
|-------|---------|
| Per source | `path`, `last_write_utc`, `length`, `hash` (SHA256), `summary` (1–2 line heuristic) |
| Governance | `status` (`ready` \| `not-ready`), `status_reason`, `inventory_hash`, `inventory_summary` |

Exit codes: `0` = `ready`; `2` = `not-ready` (still writes `sources.json` under `bank_root/.inventory/` only). Path escape / missing sources / incomplete hash → `not-ready` + reason (TE01).

**Observable wire (required):** after the script (or fallback) runs, read `status`, `status_reason`, `inventory_hash`, and `inventory_summary` from `sources.json` and include them in the Step 7 report. Do **not** treat `not-ready` as silent success — surface the reason before create/refresh file fills. Re-runs preserve paths from existing `sources.json` plus default discovery.

If script path unavailable, run equivalent Glob/Grep from `references/inventory-fallback.md` and write **only** under `<bank_root>/.inventory/` (same governance fields).

### 6. Scaffold or refresh files

| Mode | Action |
|------|--------|
| create | Copy templates from `templates/memory-bank/`; fill GENERATED regions + obvious fields from inventory/README/AGENTS (`references/template-map.md`, `references/tech-stack.md`) |
| refresh | Re-run inventory; update GENERATED regions and `tech-stack.json`; preserve human prose outside markers |
| refresh-light | Re-run inventory; update GENERATED regions and `tech-stack.json` only; do not rewrite human prose sections; append history with `action: refresh-light`. If `caveman_mode` ON and narrative files are large, **offer** (do not auto-run) compact via `COMPACT.md` for `known-risks.md` / feature `CONTINUITY.md` after inventory. |

Rules:

- Preserve `<!-- BEGIN GENERATED: … -->` / `<!-- END GENERATED: … -->` discipline (`references/generated-markers.md`)
- **No secrets** - env names / `***` only (`references/secrets.md`)
- Evidence-based domain/architecture; unknowns -> `gaps.md`
- Phase 2 (`database-schema.md`, `api-contracts.md`, `component-catalog.md`): write from templates when relevant; if Prior/cited already has DDL/OpenAPI/UI map, those files are **BLOCKING** (promote immediately or `- [ ] BLOCKING:` until written)
- Versioning / `.gitignore`: `references/versioning.md`. Dry-run checks: `references/dry-run.md`

### 7. Report + handoff

Report paths written, stack hints, blocking gaps (if any), storage mode, and **inventory governance**: `status` / `status_reason` / `inventory_hash` / `inventory_summary` (from Step 5). If `status` is `not-ready`, say so explicitly with the reason before handoff.

Handoff examples:

```text
/orchestrate-analyze
/memory-bank-init - refresh
/memory-bank-init - refresh-light
```

## Must not

- Write application / test source
- Create bank under `features/NNN-slug/`
- Require external CLI tooling (uv, specify, Spec Kit installers)
- Skip confirm-before-write
- Dump entire bank into orchestrator parent context
- Do not ignore `IC-DIRECT-ORCHESTRATED` — resolve and apply `direct` vs `orchestrated` (`INVOCATION-CONTEXTS.md`)
- Auto-commit
- Edit consumer `.gitignore` when `storage_mode` is **global**
- Add or require `/memory-bank/` in `.gitignore`
- Commit secrets into the bank (keys, tokens, connection strings, raw `.env`)
- Leave phase 2 as gaps-only when Prior/cited already has DDL, OpenAPI, or a UI component map (those files are **BLOCKING** — write/promote or `- [ ] BLOCKING:`)