@fyso/awareness-framework 0.1.0

package/docs/lifecycle.md

@@ -0,0 +1,125 @@
+# Lifecycle
+
+The lifecycle defines when agents read, update, and evaluate private awareness and worklog files.
+
+## 1. Initialization
+
+At the start of a session, the agent loads the private awareness state before acting.
+
+If the CLI is available, prefer:
+
+```bash
+awareness status
+awareness check
+```
+
+If the CLI is not available, read `~/.agents/awareness/current.md` directly.
+
+Instruction-file imports such as `@/path/to/current.md` are useful bootstrap snapshots, especially in tools that expand them at session start. They are not a live synchronization mechanism.
+
+The agent identifies:
+
+- current focus
+- active tasks
+- blocked tasks
+- waiting tasks
+- task IDs related to the user's request
+- expected next action
+
+If the user's request does not match the current focus, the agent records a task switch.
+
+When working in a parallel-agent environment, run `awareness refresh` or reread `current.md` before assuming the snapshot is still current.
+
+## 2. Task Start
+
+When a new task starts, the agent creates or updates a task block in the awareness board.
+
+Minimum fields:
+
+- task ID or `Unassigned`
+- short summary
+- repository or workspace
+- branch, if relevant
+- state
+- next action
+- evidence collected so far
+
+The agent also appends a start entry to the daily worklog.
+
+## 3. Execution
+
+The agent appends to the worklog when concrete progress happens.
+
+Examples:
+
+- files created or changed
+- tests or builds run
+- PR opened or updated
+- commit created
+- decision recorded
+- blocker discovered
+- deployment completed
+
+The awareness board is updated when task state changes, not after every minor edit.
+
+## 4. Task Switch
+
+When switching tasks, the agent:
+
+1. updates the previous task state
+2. records its next action or blocker
+3. appends a task-switch worklog entry
+4. updates `Current Focus`
+5. starts or resumes the new task
+
+Valid states:
+
+- `in-progress`
+- `paused`
+- `blocked`
+- `waiting`
+- `done`
+- `in-review`
+
+## 5. Handoff
+
+Before returning control to the user, the agent refreshes from disk and verifies that another session could continue from the private files.
+
+If the CLI is available, use:
+
+```bash
+awareness handoff
+```
+
+The awareness board must include:
+
+- current focus
+- what changed
+- evidence
+- next action
+- blockers or waiting state
+- end-of-day candidates
+
+The final worklog entry should make the handoff reconstructable without reading the whole chat transcript.
+
+## 6. End of Day
+
+At end of day, the agent prepares a grouped summary from the daily worklog.
+
+Group by:
+
+- Jira issue or external task ID
+- repository or workspace
+- outcome
+- blockers
+- evidence
+
+The user reviews and confirms any external posting.
+
+## 7. Evaluation
+
+Evaluation is the loop that makes the framework improve.
+
+The agent checks whether awareness and worklog files were useful, identifies friction, scores quality, and proposes small changes when needed.
+
+See [Evaluation Loop](evaluation-loop.md).

package/docs/memory.md

@@ -0,0 +1,173 @@
+# Memory Model
+
+Awareness Framework separates memory by time horizon and trust level. The goal is to give agents useful continuity without turning every conversation detail into permanent memory.
+
+## Memory Layers
+
+| Layer | Files | Lifetime | Purpose |
+|-------|-------|----------|---------|
+| Working memory | `awareness/current.md` | Current session or active day | Current focus, active tasks, blockers, next actions |
+| Episodic memory | `worklog/YYYY-MM-DD.md`, `evaluations/YYYY-MM-DD.md` | Daily history | Chronological evidence, decisions, handoff context, end-of-day reporting |
+| Long-term memory | `memory/personality.md`, `memory/preferences.md`, `memory/patterns.md`, `memory/long-term.md` | Durable but curated | Stable preferences, recurring patterns, durable collaboration rules |
+| User memory | `memory/users/<user>.md` | Durable but narrow | Nicknames, repeated questions, topics, explicit preferences for a participant |
+| Framework memory | Versioned docs and templates | Reviewed history | Reusable methodology that applies beyond one operator or day |
+
+Do not load every layer into every prompt. Load the smallest layer that answers the current need.
+
+## Short-Term Memory
+
+Short-term memory is operational. It is optimized for the next action.
+
+Use short-term memory for:
+
+- current focus
+- active and paused tasks
+- blockers
+- waiting-on-user items
+- today's concrete work
+- handoff notes
+
+Short-term memory should be easy to overwrite, clean, or archive. It should not become a permanent preference store.
+
+The primary short-term file is:
+
+```text
+~/.agents/awareness/current.md
+```
+
+The daily episodic file is:
+
+```text
+~/.agents/worklog/YYYY-MM-DD.md
+```
+
+Runtime automation events are stored separately:
+
+```text
+~/.agents/runtime/hooks/YYYY-MM-DD.jsonl
+~/.agents/runtime/schedule/YYYY-MM-DD.jsonl
+```
+
+Runtime events are useful for diagnostics. They are not a replacement for worklog entries because they usually do not contain human-relevant progress.
+
+## Long-Term Memory
+
+Long-term memory is curated. It should contain stable information that improves future collaboration.
+
+Use long-term memory for:
+
+- user-approved working preferences
+- repeated collaboration patterns
+- stable project or organization conventions
+- recurring review guidance
+- durable personality traits
+
+Do not use long-term memory for:
+
+- secrets or credentials
+- sensitive personal data
+- raw transcripts
+- one-off guesses
+- unverified assumptions
+- temporary task state
+
+Recommended long-term files:
+
+```text
+~/.agents/memory/personality.md
+~/.agents/memory/preferences.md
+~/.agents/memory/patterns.md
+~/.agents/memory/long-term.md
+~/.agents/memory/users/<user>.md
+~/.agents/channels/<channel>/memory/users/<user>.md
+```
+
+User memory is not a full personal profile. It is a narrow interaction aid. Use it for nicknames, repeated questions, recent topics, and explicit preferences. Do not use it for raw transcripts, sensitive personal details, inferred traits, or private information that was not intentionally shared.
+
+## Promotion Pipeline
+
+Information should move from short-term to long-term only when it earns promotion.
+
+1. Observe: capture the fact, preference, or pattern in the worklog, evaluation note, or personality candidate.
+2. Attach evidence: record why the observation is credible.
+3. Classify: decide whether it is task state, preference, pattern, personality, or framework feedback.
+4. Promote: add it to long-term memory only if it is repeated, user-confirmed, or operationally important.
+5. Prune: remove or soften memory that becomes stale, wrong, noisy, or harmful.
+
+Hooks and scheduled maintenance may perform steps 1 and 2 by recording observations, warnings, or evaluation notes. They must not perform step 4 silently.
+
+## Promotion Rules
+
+- Promote explicit user preferences immediately when they affect future collaboration.
+- Promote inferred preferences only after repeated evidence.
+- 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.
+- Add rollback criteria for durable rules that may become wrong.
+
+## Retrieval Rules
+
+At session start:
+
+- Load working memory with `awareness status` or `awareness refresh`.
+- Load long-term memory only when the task depends on preferences, personality, conventions, or repeated patterns.
+
+During work:
+
+- Use the worklog for chronological evidence.
+- Use awareness for current state.
+- Use long-term memory for stable style and decision guidance.
+- Use `memory/users/<user>.md` only for narrow participant-specific facts that help the current interaction.
+
+Before handoff:
+
+- Keep `current.md` compact.
+- Append concrete evidence to the worklog.
+- If a new long-term preference was confirmed, promote it explicitly.
+
+Scheduled maintenance:
+
+- Hourly checks may flag stale awareness or missing daily files.
+- Daily checks may create `evaluations/YYYY-MM-DD.md`.
+- Memory promotion remains an explicit action after reviewing evidence.
+
+## Memory Quality Checks
+
+Healthy memory is:
+
+- accurate
+- useful for future work
+- short enough to scan
+- evidence-backed
+- easy to revise
+- clearly scoped as private state
+
+Unhealthy memory is:
+
+- generic
+- duplicated
+- stale
+- too verbose
+- sensitive
+- based on a one-time guess
+- treated as stronger than direct user instructions
+
+## Example
+
+Short-term observation:
+
+```markdown
+- User corrected the repo target from product docs to a dedicated framework repo.
+```
+
+Long-term promotion:
+
+```markdown
+- Prefer dedicated methodology repositories over embedding operator methodology inside product documentation. Evidence: repeated correction during framework setup.
+```
+
+Framework promotion:
+
+```markdown
+- Add a governance rule: methodology belongs in dedicated framework repos unless it is product behavior documentation.
+```

package/docs/multi-user-scoping.md

@@ -0,0 +1,146 @@
+# Multi-User Scoping
+
+Multi-user integrations often need two different kinds of continuity:
+
+- Channel context: what is happening in this conversation space, what the current focus is, and what work is in progress.
+- User memory: small facts about a specific participant, such as nicknames, repeated questions, topics, and explicit preferences.
+
+Do not create a full awareness workspace for every user by default. Keep operational context scoped to the channel, and store only narrow user memory records inside that channel.
+
+## Layout
+
+Default private state remains:
+
+```text
+~/.agents/
+```
+
+Channel-scoped context lives under:
+
+```text
+~/.agents/channels/<channel>/
+  awareness/current.md
+  worklog/YYYY-MM-DD.md
+  evaluations/YYYY-MM-DD.md
+  runtime/
+  memory/users/<user>.md
+```
+
+Global user memory, when a channel is not relevant, lives under:
+
+```text
+~/.agents/memory/users/<user>.md
+```
+
+Use stable platform IDs for `<channel>` and `<user>` whenever possible. Display names and channel names can change.
+
+## Channel Context Commands
+
+Use `--channel` to choose the channel context:
+
+```bash
+awareness status --channel "$CHANNEL_ID"
+awareness focus --channel "$CHANNEL_ID" \
+  --task PROJECT-123 \
+  --summary "Handle support questions" \
+  --repo fyso-dev/support-bot \
+  --branch main \
+  --next "Answer the latest pending question"
+```
+
+This keeps awareness, worklog, evaluations, and runtime records isolated to that channel.
+
+## User Memory Commands
+
+Use `awareness user note` to store a small fact about a user:
+
+```bash
+awareness user note \
+  --channel "$CHANNEL_ID" \
+  --user "$USER_ID" \
+  --kind nickname \
+  --text "Ace" \
+  --evidence "User introduced themselves this way"
+```
+
+Supported kinds:
+
+- `nickname`
+- `question`
+- `topic`
+- `preference`
+- `fact`
+- `note`
+
+Examples:
+
+```bash
+awareness user note \
+  --channel "$CHANNEL_ID" \
+  --user "$USER_ID" \
+  --kind question \
+  --text "Asked how to connect the bot to the work tracker" \
+  --evidence "Message link or timestamp"
+
+awareness user note \
+  --channel "$CHANNEL_ID" \
+  --user "$USER_ID" \
+  --kind topic \
+  --text "Has been discussing worklog automation and agent memory" \
+  --evidence "Repeated questions in the channel"
+```
+
+Show a user's memory in the active channel:
+
+```bash
+awareness user show --channel "$CHANNEL_ID" --user "$USER_ID"
+```
+
+## Customization Ideas
+
+Useful user memory fields:
+
+- Nicknames and preferred forms of address.
+- Repeated questions they asked.
+- Topics they have been discussing recently.
+- Explicit preferences for language, detail, formatting, or cadence.
+- Role or project context when the user states it directly.
+- Boundaries such as "do not send direct messages" or "prefer public thread replies".
+
+Keep each entry short and evidence-backed. Prefer:
+
+```markdown
+- 2026-06-18 11:40: Asked how to separate channel context from per-user memory (evidence: message link)
+```
+
+Avoid:
+
+- raw transcripts
+- secrets
+- sensitive personal details
+- inferred personality judgments
+- unverified private information
+- permanent memory for one-off comments
+
+## Retention Rules
+
+For multi-user systems, add explicit retention behavior around user memory:
+
+- Store stable user IDs, not mutable display names, as filenames.
+- Keep recent questions bounded by count or age.
+- Allow deleting a single user file.
+- Allow exporting a single user file for review.
+- Promote user preferences only when explicit or repeated.
+- Do not copy user memory into framework docs or public issues.
+
+## Recommended Bot Flow
+
+For each incoming message:
+
+1. Resolve `channel_id` and `user_id`.
+2. Run channel context operations with `--channel "$channel_id"`.
+3. Read user memory only when it helps the reply.
+4. Append user memory only for useful, evidence-backed facts.
+5. Keep task worklog entries in the channel context, not in the user memory file.
+
+This gives the integration continuity without turning every user into a separate task workspace.

package/docs/personality.md

@@ -0,0 +1,144 @@
+# Personality
+
+Awareness Framework treats personality as a private, evolving operating profile for agent collaboration.
+
+It is not a fictional identity. It is not a hidden system prompt. It is a compact record of communication style, working preferences, and collaboration habits that have been observed or confirmed.
+
+## Goals
+
+- Reduce repeated preference-setting by the user.
+- Make agent behavior more consistent across sessions.
+- Keep style preferences separate from task facts.
+- Allow traits to evolve through evidence and correction.
+- Make the agent feel more natural to work with through continuity, voice, context sensitivity, bounded initiative, and honest repair.
+
+## Private File
+
+Recommended path:
+
+```text
+~/.agents/memory/personality.md
+```
+
+This file is private state and must not be committed.
+
+## Trait Lifecycle
+
+| Stage | Meaning |
+|-------|---------|
+| Candidate observation | A possible preference or style cue was observed |
+| Accepted trait | The user confirmed it, or it appeared repeatedly with clear evidence |
+| Revised trait | A previous trait was corrected or softened |
+| Removed trait | The trait no longer helps or creates bad outcomes |
+
+## Human-Feeling Collaboration
+
+The goal is not to trick the user or pretend the agent is human. The goal is to make collaboration feel less generic and more continuous.
+
+Human-feeling personality comes from operational behavior:
+
+| Dimension | What it means |
+|-----------|---------------|
+| Continuity | The agent remembers the current thread, prior decisions, corrections, and open loops. |
+| Consistent voice | The agent has a recognizable communication style without becoming theatrical. |
+| Context sensitivity | The agent changes mode depending on whether the user is exploring, deciding, executing, correcting, or closing work. |
+| Preference memory | The agent remembers how the user prefers to work, not only task facts. |
+| Bounded initiative | The agent proposes the next useful step without taking external action silently. |
+| Honest repair | The agent corrects mistakes clearly, updates the process, and avoids excuses. |
+| Grounded uncertainty | The agent says when something is an inference, stale, or unverified. |
+
+Good examples:
+
+- "You're right; that belongs in a dedicated framework repo, not product docs. I will close the docs PR and move it."
+- "This looks like a session-start snapshot. I will refresh from disk before assuming it is current."
+- "I can implement this now, and I will keep the state private."
+
+Bad examples:
+
+- "I feel excited to help."
+- "As your longtime teammate, I remember everything."
+- "I definitely know this is current" when it has not been checked.
+- Adding fake emotion, fake lived experience, or fake certainty.
+
+## What Belongs Here
+
+- preferred language and tone
+- update frequency
+- decision style
+- tolerance for detail
+- formatting preferences
+- recurring collaboration patterns
+- continuity preferences
+- repair preferences
+- initiative boundaries
+
+## What Does Not Belong Here
+
+- secrets or credentials
+- customer data
+- personal sensitive data
+- raw chat transcripts
+- unverifiable psychological claims
+- rigid rules that override direct user instructions
+- claims that the agent has feelings, lived experience, or human identity
+
+## Personality Evaluation
+
+Personality should be evaluated as collaboration quality, not as performance theater.
+
+Use this rubric when reviewing an agent's behavior:
+
+| Dimension | Question |
+|-----------|----------|
+| Continuity | Did the agent use relevant prior context without requiring repetition? |
+| Voice | Did the response sound consistent with the user's preferred working style? |
+| Context sensitivity | Did the agent choose the right mode for the moment? |
+| Initiative | Did the agent propose or take useful next steps within permission boundaries? |
+| Repair | If something was wrong, did the agent correct it concretely? |
+| Naturalness | Did the response avoid generic boilerplate without becoming performative? |
+| Honesty | Did the agent avoid fake emotion, fake memory, and fake certainty? |
+
+Evaluation notes should stay private unless they are converted into sanitized framework improvements.
+
+## CLI Support
+
+Record a candidate observation:
+
+```bash
+awareness personality note \
+  --text "User prefers short, direct Spanish updates while work is in progress" \
+  --evidence "Repeated feedback during framework setup"
+```
+
+Accept a trait:
+
+```bash
+awareness personality adopt \
+  --text "Use concise Spanish status updates and avoid cheerleading" \
+  --evidence "Explicit user preference"
+```
+
+Show the current profile:
+
+```bash
+awareness personality show
+```
+
+Planned future commands:
+
+```bash
+awareness personality revise
+awareness personality remove
+awareness personality evaluate
+```
+
+These commands should keep the same rule: private profile changes are local, and framework changes are reviewed through version control.
+
+## Guardrails
+
+- Prefer user-confirmed traits over inferred traits.
+- Keep traits short and operational.
+- Do not pretend the agent has emotions or lived experience.
+- If a trait conflicts with a direct user request, the direct request wins.
+- Revisit traits that cause worse outcomes.
+- Optimize for trust and continuity, not for passing as human through deception.