Awareness Framework

Awareness Framework is a working methodology for humans who use multiple AI agents across parallel tasks. It gives agents a shared operational protocol for current focus, task handoff, daily worklogs, and process evaluation without depending on hidden model memory.

This repository contains the framework, templates, and governance rules. It must not contain real awareness boards, daily worklogs, personal memories, customer details, or private task state.

What This Is

• A methodology for agent-assisted work.
• A shared vocabulary for awareness, worklog, handoff, and evaluation.
• A set of templates that can be copied into private local state.
• An optional helper CLI that maintains and checks private state.
• A reviewable process for improving the methodology over time.

What This Is Not

• Not a task manager.
• Not dependent on a CLI tool.
• Not a Jira replacement.
• Not a vector memory product.
• Not a place to store private operational state.

Core Artifacts

Artifact	Versioned here?	Purpose
Framework docs	Yes	Canonical methodology and rules
Templates	Yes	Sanitized starting points
Awareness board	No	Mutable private current state
Daily worklog	No	Append-only private record of the day
Personal memory	No	Durable private preferences and patterns
Evaluation notes	No by default	Private observations used to propose framework improvements

Personality is treated as a private operating profile: continuity, voice, context sensitivity, bounded initiative, and honest repair. It must not become fake emotion, fake identity, or hidden autonomy.

Recommended Private Layout

~/.agents/
  AGENTS.md
  awareness/
    current.md
  worklog/
    YYYY-MM-DD.md
  memory/
    preferences.md
    patterns.md
    long-term.md
    events.jsonl
    users/
      <user>.md
  evaluations/
    YYYY-MM-DD.md
  runtime/
    hooks/
    schedule/
    metrics/
  channels/
    <channel>/
      awareness/
      worklog/
      memory/
        users/

Method

1. At session start, the agent loads private awareness state. If the CLI is available, it runs awareness status or awareness check; otherwise it reads the private awareness board.
2. When focus changes, the agent updates awareness and appends a task-switch worklog entry.
3. When concrete progress happens, the agent appends a worklog entry with evidence.
4. Before handoff, or when parallel work may have changed state, the agent refreshes from disk and leaves a clear current state and next action.
5. At end of day, the agent prepares a task-grouped summary for human review.
6. During evaluation, the agent identifies process friction and proposes framework changes through PRs.

Documentation

• Install
• Framework
• Lifecycle
• Private State
• Evaluation Loop
• Memory Model
• Multi-User Scoping
• Hooks and Scheduling
• CLI
• Personality
• Adoption Guide
• Governance

Templates

• Agent instructions
• CLI wrapper
• Awareness board
• Daily worklog
• End-of-day summary
• Evaluation note
• Framework improvement proposal
• Personality profile

CLI Quick Start

npm install -g @fyso/awareness-framework
awareness init
awareness init --wrappers
awareness update
awareness status
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 memory stats --since 7d
awareness improve

memory/events.jsonl stores the local memory event history, including memory.used credits. runtime/recall/*.jsonl keeps recall usage and curated hit attribution.

The CLI only reads and writes private local files. It does not post to Jira, GitHub, or any external system.