@fyso/awareness-framework 0.2.0 → 0.3.1

package/README.md

@@ -46,6 +46,7 @@ Personality is treated as a private operating profile: continuity, voice, contex
     preferences.md
     patterns.md
     long-term.md
+    events.jsonl
     users/
       <user>.md
   evaluations/
@@ -107,6 +108,9 @@ awareness refresh
 awareness check
 awareness hook install --tool all --command "$(command -v awareness)"
 awareness schedule install --cadence all --command "$(command -v awareness)"
+awareness remember --text "Useful local observation" --evidence "Source"
+awareness recall "local observation"
+awareness improve
 ```
 
 The CLI only reads and writes private local files. It does not post to Jira, GitHub, or any external system.

package/docs/cli.md

@@ -118,7 +118,7 @@ awareness init --wrappers \
 
 ### `status`
 
-Shows the current focus and warnings.
+Shows the current focus and warnings. Warnings are printed but do not make the command fail; use `awareness check --strict` when automation should fail on warnings.
 
 ```bash
 awareness status
@@ -153,9 +153,12 @@ awareness focus \
   --summary "Agent awareness framework" \
   --repo fyso-dev/awareness-framework \
   --branch codex/cli-and-personality \
+  --state in-progress \
   --next "Run tests and open a PR"
 ```
 
+Valid states are `started`, `in-progress`, `paused`, `blocked`, `waiting`, `done`, `in-review`, and `ready`. Underscore aliases such as `in_progress` and `in_review` are accepted and normalized.
+
 ### `log`
 
 Appends a concrete progress entry to the daily worklog.
@@ -170,7 +173,7 @@ awareness log \
 
 ### `handoff`
 
-Prints a handoff snapshot from the awareness board.
+Prints a handoff snapshot from the awareness board. Like `status`, warnings are informational and return exit code 0.
 
 ```bash
 awareness handoff
@@ -186,7 +189,41 @@ awareness evaluate --print
 awareness evaluate --force
 ```
 
-The CLI does not automatically change the framework. Repeated findings should become reviewed framework changes.
+When an evaluation is written, the CLI also records low-risk promotion candidates in `memory/long-term.md`. It does not silently promote candidates into durable rules; use `awareness memory promote` after review.
+
+### `memory`
+
+Reviews and promotes long-term memory.
+
+```bash
+awareness memory candidates
+awareness memory review
+awareness memory review --min-count 3
+awareness memory note --text "User prefers active memory review" --evidence "Direct request"
+awareness memory promote --kind preference --text "Surface memory candidates proactively" --evidence "User confirmed"
+```
+
+`memory review` scans promotion candidates and suggests repeated candidates as `pattern` promotions once they appear at least twice by default.
+
+`memory candidates` lists active promotion candidates only. Text that has been pruned or revised remains in the Markdown history but is hidden from active candidates, excluded from suggestions, and rejected by `memory promote`.
+
+Valid promotion kinds are `preference`, `pattern`, `project`, and `review`.
+
+### Local memory operations
+
+These commands provide a small Cognee-inspired operation vocabulary without adding a graph database or vector store.
+
+```bash
+awareness remember --text "Prefer recall before repeating implementation work" --evidence "User request"
+awareness recall "implementation work"
+awareness forget --text "Old assumption" --reason "Superseded by user correction" --evidence "Correction message"
+awareness improve
+```
+
+`remember` records a promotion candidate and appends `memory.candidate.created` to `memory/events.jsonl`.
+`recall` performs deterministic local text search across memory, memory events, worklogs, and evaluations. Matching is case- and accent-insensitive, includes simple singular/plural normalization, and includes a small English/Spanish alias set for memory/user terms.
+`forget` records a prune/revision entry and appends `memory.pruned`; it does not destructively delete historical evidence, but pruned text is inactive for candidate review and promotion.
+`improve` runs the evaluation/review loop and appends `evaluation.created` and `pattern.suggested` events when applicable. Auto-generated evaluation candidates are deduplicated by text across days so recurring diagnostics do not flood human-curated candidates.
 
 ### `hook run`
 

package/docs/evaluation-loop.md

@@ -115,6 +115,8 @@ Each evaluation should end with one of these outcomes:
 - Propose framework PR.
 - Ask user for confirmation.
 
+Daily evaluation is active by default: when it writes an evaluation note, the CLI also records promotion candidates under `memory/long-term.md`. Auto-generated candidates are deduplicated by text across days so repeated diagnostics do not crowd out human-curated observations. Candidates are intentionally reviewable. Use `awareness memory review` to surface repeated candidates as suggested `pattern` promotions, then promote them with `awareness memory promote` only after they are user-confirmed, repeated, operationally important, and not pruned or revised.
+
 ## Example Outcomes
 
 | Observation | Improvement |

package/docs/lifecycle.md

@@ -74,12 +74,16 @@ When switching tasks, the agent:
 
 Valid states:
 
+- `started`
 - `in-progress`
 - `paused`
 - `blocked`
 - `waiting`
 - `done`
 - `in-review`
+- `ready`
+
+The CLI also accepts underscore aliases such as `in_progress` and normalizes them to hyphenated state names.
 
 ## 5. Handoff
 

package/docs/memory.md

@@ -14,6 +14,23 @@ Awareness Framework separates memory by time horizon and trust level. The goal i
 
 Do not load every layer into every prompt. Load the smallest layer that answers the current need.
 
+## Local Operation Model
+
+Awareness uses a small local operation vocabulary:
+
+- `remember`: capture an evidence-backed candidate.
+- `recall`: search local memory, events, worklogs, and evaluations with deterministic normalized text matching.
+- `forget`: prune or revise stale memory without destructive deletion.
+- `improve`: run evaluation plus memory review to surface repeated candidates.
+
+The append-only event log lives at:
+
+```text
+~/.agents/memory/events.jsonl
+```
+
+Markdown files remain the readable projection. The event log is the auditable history of memory operations.
+
 ## Short-Term Memory
 
 Short-term memory is operational. It is optimized for the next action.
@@ -96,10 +113,13 @@ Information should move from short-term to long-term only when it earns promotio
 
 Hooks and scheduled maintenance may perform steps 1 and 2 by recording observations, warnings, or evaluation notes. They must not perform step 4 silently.
 
+Pruned or revised text remains in the Markdown history for auditability, but it is inactive. It should not appear in active candidate listings, repeated-candidate suggestions, or promotion commands.
+
 ## Promotion Rules
 
 - Promote explicit user preferences immediately when they affect future collaboration.
 - Promote inferred preferences only after repeated evidence.
+- Do not promote text that has been pruned or revised; record a new corrected candidate instead.
 - Promote framework changes only through version control.
 - Keep private memory private; do not copy private examples into public docs.
 - Prefer small, operational statements over long stories.