How Thoughts Work

The thoughts system gives AI agents persistent context about your codebase across sessions and team members. It’s a shared repository of knowledge — research findings, implementation plans, PR descriptions, handoff documents — that lives outside your code repository.

Architecture

~/thoughts/                    # Shared thoughts repository (git repo)
  ├── repos/                   # Project-specific thoughts
  │   ├── my-project/
  │   │   ├── alice/           # Alice's personal thoughts
  │   │   └── shared/          # Team-shared thoughts for this project
  │   │       ├── plans/       # Implementation plans
  │   │       ├── prs/         # PR descriptions
  │   │       └── handoffs/    # Handoff documents
  │   └── another-project/
  │       ├── bob/
  │       └── shared/
  └── global/                  # Cross-project thoughts
      ├── alice/
      ├── bob/
      └── shared/

Symlink Structure

When you run hyprlayer thoughts init in a project, it creates a thoughts/ directory with symlinks pointing into the shared repository:

my-project/
  └── thoughts/
       ├── alice/     → ~/thoughts/repos/my-project/alice/
       ├── shared/    → ~/thoughts/repos/my-project/shared/
       └── global/    → ~/thoughts/global/

This means:

• AI agents read and write to thoughts/ as if it’s a local directory
• Changes are actually stored in the shared thoughts repository
• The thoughts/ directory is never committed to your code repository (protected by a pre-commit hook)

Searchable Index

When you run hyprlayer thoughts sync, it creates a thoughts/searchable/ directory containing hard links to all files across the symlinked directories. This gives AI agents a flat, searchable view of all thoughts without needing to follow symlinks.

Personal vs Shared

• thoughts/<username>/ — Your personal notes, research, and drafts. Only you write here.
• thoughts/shared/ — Team-shared artifacts: plans, PR descriptions, handoffs, templates.
• thoughts/global/ — Cross-project knowledge shared across all repositories.

Git Integration

The thoughts repository is a standard git repository. Hyprlayer manages it with:

• Auto-sync — A post-commit hook automatically syncs thoughts after each code commit
• Manual sync — Run hyprlayer thoughts sync to sync on demand
• Remote support — If the thoughts repo has a remote, sync pulls and pushes automatically