8.1 KiB
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, refinement and Plan consolidation 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:
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:
aie gate record WRK-0001 project/tests --expect <evaluatedHash> \
--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 documents those file formats. Storage migration 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.