@fyso/awareness-framework 0.2.0 → 0.3.0

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

@@ -186,7 +186,39 @@ 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.
+
+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.
+`forget` records a prune/revision entry and appends `memory.pruned`; it does not destructively delete historical evidence.
+`improve` runs the evaluation/review loop and appends `evaluation.created` and `pattern.suggested` events when applicable.
 
 ### `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`. 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, or operationally important.
+
 ## Example Outcomes
 
 | Observation | Improvement |

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.
+- `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.