# Local engineering memory protocol AIE is a local framework per project. `.ai-engineering/aie.db` owns operational memory: Works, investigation, decisions, Plans, execution facts and gate results. Small YAML/JSON and README/AGENTS files bootstrap discovery and configuration. There is no database server or background process. Git and source repositories are optional; synchronization, distributed IDs, Git LFS and Work/DEC export are outside this version. ## Starting and continuing Run `aie status`, `aie next-actions`, then `aie work context WRK-0001`. The closest enclosing `.ai-engineering` owns the project. `--project PATH` selects one explicitly. A SQLite workspace requires a compatible CLI; unavailable or unreadable memory must be reported, never treated as an empty project. `init --name TEXT` defaults to SQLite and adds `/.ai-engineering/` to .gitignore. `--version-state` leaves ignore policy to the developer without removing existing rules. Existing tracked files are not untracked. `--storage legacy` is an explicit compatibility option. Neither reads, `onboard`, nor installation migrate storage. Work IDs are uppercase hexadecimal (`WRK-000A`); child IDs are decimal and local to their Work (`DEC-0001`, `PLN-0001`, `TSK-0001`). The database transaction reserves new identities and owned references together. Migration preserves reserved gaps. ## Investigation and implementation Discussion/investigation and implementation remain separate cycles connected by DEC and Plan. Work stores scope, criteria and useful refinement; topics, surveys, answer supersession and explicit conclusions preserve continuity. OODA is adaptive: observe results, reconsider assumptions, decide and act. It is not a four-step ritual imposed on every edit. Ask for DIRECT or EXPLORATORY when unspecified. Only the human chooses/changes the mode or ends exploration. Record choices with `work guidance --human-approved`; exploratory DEC emission needs `work request-decision`. Human DEC approval is the default. Direct mode does not waive it. An explicit Work-wide waiver is recorded separately. Never infer approval from an adapter proposal or status label. Accepted DECs are immutable; revisions/supersession retain their authority and history. Plans require applicable accepted decisions and resolved discussion. Steps have dependencies, criteria and results. Relevant experiments record their hypothesis/criterion before execution and observations/interpretation afterward. Failed hypotheses require reconsideration before retry; DEC concerns block affected execution until the accepted replacement is referenced. See [Work guidance/OODA](work-guidance.md), [refinement](discussion-slice.md) and [Plan consolidation](plan-consolidation.md) for command details. ## Quality gates Required project gates and additional Work gates are cumulative. A Work cannot replace a project gate by reusing its local name. Define the procedure and relevant input files/directories before evaluating it: ```sh aie gate configure tests --title "Project tests" --procedure "./gradlew check" \ --input src --input build.gradle.kts --require-evidence --by owner aie gate configure review --work WRK-0001 --title "Work review" \ --procedure "Review the DEC criteria" --input src --by owner aie gate status WRK-0001 --format json ``` Obtain `evaluatedHash` before running the procedure externally. Attach required small evidence with `artifact add`. Then record the actual result: ```sh aie gate record WRK-0001 project/tests --expect \ --invocation "./gradlew check" --outcome PASS --summary "Observed checks passed" \ --evidence ART-0001 --by observer --observed ``` `--observed` attests an actual external check; it is not human DEC approval. AIE does not execute the procedure or establish the semantic truth of a claim. Results retain definition, invocation, scope/input fingerprint, moment, observer, outcome and short summary. `gate history` exposes prior observations. Changed inputs, Work scope/guidance, DEC revisions or gate definitions require evaluation again. Plan/status bookkeeping does not invalidate the check. Pending, failed or stale gates prevent manual, Plan and EPIC delivery. Completion freezes references/hashes of the actual gate results in the same transaction. Later source/policy changes do not invent checks on old deliveries; reopened work requires applicable current results. Imported deliveries keep their historical contract, without fabricated retroactive gates. ## Temporary inputs and outputs `artifact add WRK --file PATH --purpose TEXT` copies a small input to the filesystem with owned integrity metadata; bytes never become BLOB, base64 or file-shaped TEXT in SQLite. Inputs remain available during dependent checks. Finishing a partial step or gate alone does not mean all future Work checks have consumed an input. At Work completion, integrity and completion facts commit before eligible payloads are removed. AVAILABLE, DISCARD_PENDING and DISCARDED distinguish usable input, interrupted cleanup and legitimate retirement. Current evaluations require available inputs; a retired artifact cannot be reused after reopening. Historical queries use the validated result, and missing input before evaluation remains an error. `artifact recover WRK` finishes interrupted publication/retirement. Reads only expose recovery actions. Publication journals identify owned residue; unknown files require inspection. Adapter process workspaces are temporary and cleaned at execution end. New Plan/EPIC receipts are structured facts, without an extra JSON file. Imported originals and migration safety copies remain preserved until explicit disposition. Requested documents/images/other deliverables belong at their output destination, outside `.ai-engineering`; code stays in the source repository. AIE does not require a permanent duplicate solely for auditing. Cleanup targets owned temporary copies, never the source/deliverable. ## Persistence, consistency and recovery SQLite uses foreign keys, WAL, FULL durability, IMMEDIATE writes and bounded writer waits. Nested domain mutations share the transaction; related reads use a snapshot. An OS publication lock coordinates writers with storage activation/rollback, with bounded waits for SQLite commands. Backend changes during a wait require a retry. Typed columns and ordered child rows retain domain data. Nullable historical lists remain distinct from empty lists. Revision hashes reconstruct the relevant typed representation or verify retained original bytes. Migration also compares original representations to typed records, detecting changed historical rows. RUN application is transactional on SQLite. Failure rolls back the whole proposal; a separate failure record has a short diagnostic and no rolled-back applied refs. Request IDs retain idempotence. Adapters cannot answer for humans, approve DECs, complete Works or execute repository commands through this framework. Legacy storage retains its per-file publication/recovery behavior. Supported legacy records remain readable; [the legacy reference](legacy-file-storage.md) documents those file formats. [Storage migration](storage-migration.md) is explicit, staged, verified and recoverable. No consumer or installed executable is automatically converted by a new build. ## Verification and closure `project validate` checks the project, identities, graph, references, history and integrity. `work validate` scopes checks to selected memory and its dependencies. `work check` reports mechanical readiness, not semantic proof of prose criteria. `status`, `next-actions` and context are read-only projections. Required completed Plans consolidate through SYSTEM_PLANS receipts; RESULTS EPICs still need explicit current authorization, and DECOMPOSITION remains reviewed. Empty sets, open questions/experiments, unresolved DEC concerns and unfinished scope remain pending. Cancelled content needs explicit scope review. Reopening preserves history and does not immediately reconclude unchanged old Plans. Archive preserves memory, not an obligation to retain every temporary file. Exit codes: 0 success, 1 I/O/runtime, 2 invalid input, 3 missing resource, 4 validation or readiness failure. Use command `--help` for exact options.