@fyso/awareness-framework 0.1.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/hooks-and-scheduling.md

@@ -31,13 +31,19 @@ These files are private operational state. Do not commit them.
 
 | Lifecycle point | Command | Purpose |
 |-----------------|---------|---------|
-| Session start or resume | `awareness hook run --tool TOOL --event session-start` | Ensure private files exist and record that the agent refreshed awareness. |
+| Session start or resume | `awareness hook run --tool TOOL --event session-start` | Ensure private files exist, record that the agent refreshed awareness, and print the Current Focus so the host injects it as context. |
 | Stop or session end | `awareness hook run --tool TOOL --event stop` | Record that the agent reached an idle or handoff boundary. |
 | Pre-compaction | `awareness hook run --tool TOOL --event pre-compact` | Record a compaction boundary before context is summarized. |
-| Post-compaction | `awareness hook run --tool TOOL --event post-compact` | Record that the new compacted context may need `awareness refresh`. |
+| Post-compaction | `awareness hook run --tool TOOL --event post-compact` | Record that the new compacted context may need `awareness refresh`, and re-print the Current Focus so it survives compaction. |
 
 Hooks should not append daily worklog entries on every lifecycle event. The worklog is for human-relevant progress with task IDs and evidence.
 
+## Context Injection
+
+`session-start` and `post-compact` are **context-injection events**: hosts such as Claude Code append the hook's stdout to the agent's context. For these events `awareness hook run` always prints the `Current Focus` block (framed as a load-this-first instruction), so the agent actively loads its focus instead of relying on a passive, possibly stale file import.
+
+`--quiet` only suppresses the diagnostic lines (`Hook recorded`, `Runtime log`, `Warnings`). It does **not** suppress the focus payload — the installed hooks pass `--quiet` precisely so the only thing reaching the agent's context is the focus itself. Non-injection events (`stop`, `session-end`, `pre-compact`) never print the focus.
+
 ## Scheduled Cadence
 
 | Cadence | Command | Purpose |

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.