How Thoughts Work

The thoughts system keeps your AI agents in context on the codebase between sessions and across your team. It’s a shared repository of research findings, implementation plans, PR descriptions, and handoff documents, and it lives outside your code repository.

Note

This page describes the git backend (the default). Hyprlayer also supports Obsidian, Notion, and Anytype as storage backends. See Storage Backends for the full matrix.

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

hyprlayer thoughts init creates a thoughts/ directory in your project, 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/

So:

• AI agents read and write thoughts/ as if it were a local directory
• The shared thoughts repository holds every change they make
• A pre-commit hook stops the thoughts/ directory from reaching your code repository

Searchable Index

hyprlayer thoughts sync creates a thoughts/searchable/ directory of hard links to every file across the symlinked directories. Agents get a flat, searchable view and never have to follow a symlink.

Personal vs Shared

• thoughts/<username>/: your personal notes, research, and drafts. Only you write here.
• thoughts/shared/: team artifacts. Plans, PR descriptions, handoffs, templates.
• thoughts/global/: knowledge your team shares across every repository.

Git Integration

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

• Auto-sync. A post-commit hook syncs thoughts after each code commit
• Manual sync. Run hyprlayer thoughts sync on demand
• Remote support. Sync pulls and pushes whenever the thoughts repo has a remote