GitHub - noahatfin/telos: Agent-first intent and constraint tracking layer for Git. Structured, queryable memory for AI coding agents.

Agent-first intent and constraint tracking layer for Git.

Quick Start · Core Concepts · CLI Reference · For AI Agents · Design Doc

🚧 Status: Active Development Telos is under rapid, active development. APIs, CLI interfaces, and storage formats may change between versions. We are currently running real-agent experiments to validate the core hypothesis — see docs/experiments/ for iteration records and findings.

Motivation

Git tracks what changed in code. But AI agents — and human developers — need to know why: what was intended, what constraints must be respected, what decisions were made and why.

This context lives in commit messages, PR descriptions, Slack threads, and developer memory — all unstructured, unsearchable, and invisible to agents starting a new session.

Telos captures intent, constraints, decisions, and code bindings in a structured, queryable, content-addressable store that sits alongside Git — giving AI agents persistent memory across sessions.

What is Telos?

Git tracks	Telos tracks
File diffs	Intents — what you set out to do
Commit messages	Constraints — rules that must/should/prefer be followed
Blame	Decisions — choices made, alternatives rejected, rationale
File paths	Code Bindings — which constraints apply to which code
—	Agent Operations — what AI agents did, why, and with what result

Every object is content-addressed (SHA-256), immutable, and forms a DAG — the same architecture as Git, applied to development reasoning.

Why Telos over flat files?

A CONSTRAINTS.md or ADR directory captures the same information. Telos's advantage is queryability:

# Flat file: grep and hope
grep -r "authentication" docs/decisions/

# Telos: structured, scoped queries
telos query constraints --file src/auth/mod.rs       # What constraints apply to this file?
telos query constraints --symbol validate_token       # What about this function?
telos query constraints --impact security --json      # All active security constraints
telos query agent-ops --agent claude-review           # What did this agent do?

Quick Start

Build from source

git clone https://github.com/noahatfin/telos.git
cd telos
cargo build --release
# Binary: target/release/telos-cli

Prerequisites: Rust toolchain 1.70+

Basic workflow

# 1. Initialize
telos init

# 2. Capture intent
telos intent \
  --statement "Add user authentication with JWT tokens" \
  --constraint "Sessions must expire after 24 hours" \
  --impact auth --impact security

# 3. Create standalone constraints with lifecycle
telos constraint \
  --statement "All API endpoints must use HTTPS" \
  --severity must --impact security

# 4. Record decisions
telos decide \
  --intent abc1234 \
  --question "Which JWT library?" \
  --decision "Use jsonwebtoken crate" \
  --rationale "Most popular, well-maintained" \
  --tag architecture

# 5. Bind constraints to code
telos bind abc1234 --file src/auth/mod.rs --symbol validate_token --type function

# 6. Query
telos context --impact auth --json              # Everything about auth
telos query constraints --file src/auth/mod.rs  # Constraints on this file
telos query agent-ops --agent claude-review     # Agent history

# 7. Constraint lifecycle
telos supersede abc1234 --statement "Updated requirement" --reason "Policy change"
telos deprecate def5678 --reason "Feature removed"

# 8. Validate & maintain
telos check --bindings    # Are code bindings still valid?
telos reindex             # Rebuild query indexes

Core Concepts

erDiagram
    IntentStream ||--o{ Intent : "tip points to"
    Intent ||--o{ Intent : "parent (DAG)"
    Intent ||--o{ DecisionRecord : "linked by intent_id"
    Intent ||--o| BehaviorDiff : "optional ref"
    Constraint ||--o| Constraint : "superseded_by"
    Constraint }o--|| Intent : "source_intent"
    CodeBinding }o--|| Constraint : "bound_object"
    CodeBinding }o--|| Intent : "bound_object"
    AgentOperation }o--o{ Intent : "context_refs"
    ChangeSet }o--o{ Intent : "intents"
    ChangeSet }o--o{ Constraint : "constraints"
    ChangeSet }o--o{ CodeBinding : "code_bindings"

Object	Description
Intent	A unit of developer purpose — statement, constraints, behavioral expectations, and impact tags. Forms a DAG via parent links.
Constraint	A first-class rule with lifecycle (`Active → Superseded / Deprecated`), severity (`Must / Should / Prefer`), and code scope.
DecisionRecord	An architectural decision linked to an intent — question, chosen option, rationale, and rejected alternatives.
CodeBinding	Links a Telos object to a code location — file, function, module, API, or type.
AgentOperation	Logs what an AI agent did — operation type, result, files touched, context references.
ChangeSet	Bridges a Git commit to its Telos reasoning chain — intents, constraints, decisions, bindings, and agent ops.
BehaviorDiff	Describes behavioral changes introduced by an intent — impact radius and verification status.
IntentStream	A named branch of intents (analogous to a Git branch).

Architecture

                    ┌──────────────────────────────────────────────────┐
                    │                    telos-cli                      │
                    │  init · intent · decide · log · show · query     │
                    │  context · stream · constraint · supersede       │
                    │  deprecate · bind · check · agent-log · reindex  │
                    │  impact · graph · coverage · timeline · sync     │
                    ├──────────────────────────────────────────────────┤
                    │                   telos-store                     │
                    │  ObjectDatabase · RefStore · IndexStore           │
                    │  Repository · Query · Lockfile                   │
                    ├──────────────────────────────────────────────────┤
                    │                   telos-core                      │
                    │  Intent · Constraint · DecisionRecord            │
                    │  CodeBinding · AgentOperation · ChangeSet        │
                    │  BehaviorDiff · ObjectId (SHA-256)               │
                    └──────────────────────────────────────────────────┘

Crate	Role
telos-core	Domain types and content-addressable hashing. Canonical JSON + SHA-256.
telos-store	Storage engine: fan-out object database, ref store, JSON query indexes, lockfile-based atomic writes.
telos-cli	Command-line interface (clap). All read commands support `--json` for agent consumption.

.telos/ directory layout

.telos/
├── HEAD                          # "ref: refs/streams/main"
├── config.json                   # Repository metadata
├── objects/                      # Content-addressable store
│   ├── a3/                       # Fan-out by first 2 hex chars
│   │   └── f29c...(62 chars)    # Object file (canonical JSON)
│   └── ...
├── indexes/                      # Query acceleration (rebuildable)
│   ├── impact.json              # impact_tag → [ObjectId]
│   ├── codepath.json            # file_path → [ObjectId]
│   └── symbols.json             # symbol_name → [ObjectId]
├── refs/
│   └── streams/
│       ├── main                  # Default stream
│       └── feature-auth          # User-created stream
└── logs/
    └── streams/                  # Stream operation logs

CLI Reference

Core commands

Command	Synopsis	Description
`init`	`telos init`	Initialize a `.telos/` repository
`intent`	`telos intent -s <statement> [--constraint ...] [--impact ...] [--behavior ...]`	Create a new intent
`decide`	`telos decide --intent <id> --question <q> --decision <d> [--rationale ...] [--tag ...]`	Record a decision
`log`	`telos log [-n <count>] [--json]`	Show intent history
`show`	`telos show <id> [--json]`	Display any object by ID or prefix

Constraint lifecycle

Command	Synopsis	Description
`constraint`	`telos constraint -s <statement> --severity <must\|should\|prefer> [--impact ...]`	Create a standalone constraint
`supersede`	`telos supersede <id> -s <new_statement> [--reason ...]`	Replace a constraint with a new version
`deprecate`	`telos deprecate <id> --reason <reason>`	Deprecate a constraint

Code bindings

Command	Synopsis	Description
`bind`	`telos bind <object_id> --file <path> [--symbol <name>] [--type file\|function\|module\|api\|type]`	Bind an object to a code location
`check`	`telos check --bindings`	Validate that code bindings still resolve

Queries

Command	Synopsis	Description
`query intents`	`telos query intents [--impact <area>] [--constraint-contains <text>] [--json]`	Find intents
`query decisions`	`telos query decisions [--intent <id>] [--tag <tag>] [--json]`	Find decisions
`query constraints`	`telos query constraints [--file <path>] [--symbol <name>] [--impact <area>] [--status active\|superseded\|deprecated] [--json]`	Find constraints (code-aware)
`query agent-ops`	`telos query agent-ops [--agent <id>] [--session <id>] [--json]`	Find agent operations
`context`	`telos context --impact <area> [--json]`	Aggregate intents + decisions for an impact area

Agent operations

Command	Synopsis	Description
`agent-log`	`telos agent-log --agent <id> --session <id> --operation <type> --summary <text> [--file ...] [--context-ref ...]`	Log an agent operation

Visualization & governance

Command	Synopsis	Description
`impact`	`telos impact <path> [--commit <sha>] [--json]`	Show constraints, intents, and decisions affecting a file, directory, or commit
`graph`	`telos graph [--impact <area>] [--id <id>] [--depth <n>] [--json]`	Visualize intent → constraint → code relationship DAG
`coverage`	`telos coverage [--dir <path>] [--json]`	Constraint coverage heatmap across source files
`timeline`	`telos timeline [--impact <area>] [--json]`	Constraint lifecycle timeline (created, superseded, deprecated)

Example: telos impact

Impact: src/auth/middleware.rs
──────────────────────────────

Constraints (2):
  [Must]   ● "Default role must be Member, never Admin"
             constraint 21c8ebb · bound to validate_token()
  [Should] ● "Auth middleware latency < 5ms"
             constraint 3051473 · bound to file

Intents (1):
  intent f633b9f "Enforce RBAC through JWT validation"
  └─ 1 decision recorded

Example: telos graph

Intent f633b9f "Enforce RBAC through JWT validation"
│ dev@example.com · 2026-03-02 · impacts: auth, security
│
├─ [Must]   ● constraint 21c8ebb
│  "Default role must be Member, never Admin"
│  └─ src/auth/middleware.rs :: validate_token
│
├─ [Must]   ● constraint 14f4d5e
│  "Token expiry must be <= 1 hour"
│  └─ src/auth/config.rs :: token_lifetime
│
└─ decision fe4be05
   Q: What should the default role be?
   A: Member
   Rejected: Admin, Viewer

Example: telos coverage

Constraint Coverage
───────────────────

src/
├─ auth/
│  ├─ middleware.rs ████████ 2 constraints
│  ├─ config.rs     ████░░░░ 1 constraint
│  └─ role.rs       ░░░░░░░░ -
└─ payments/
   ├─ handler.rs    ░░░░░░░░ -
   └─ ledger.rs     ░░░░░░░░ -

Summary: 3 constraints across 2/5 files (40%)
         3 files uncovered

Example: telos timeline

Constraint Timeline
───────────────────

14f4d5e [Must]   "Token expiry must be <= 1 hour"
  ● Created     2026-02-10  dev@example.com
    (active 20d)

fe773c7 [Should] "Auth middleware latency < 5ms"
  ● Created     2026-02-12  dev@example.com
  ▲ Superseded  2026-02-25  dev@example.com
    └─ by 3410d1a

Active: 3  Superseded: 1  Deprecated: 0

Agent sync

Command	Synopsis	Description
`sync`	`telos sync --target claude\|codex\|generic [--only-must] [--all] [--dry-run] [--remove]`	Export active constraints to agent memory files (CLAUDE.md, etc.)

Maintenance

Command	Synopsis	Description
`reindex`	`telos reindex`	Rebuild all query indexes from the object store
`stream`	`telos stream create\|list\|switch\|delete <name>`	Manage intent streams

For AI Agents

Telos is built agent-first. Every read command supports --json:

# Recover context at session start
telos context --impact auth --json

# Check constraints before modifying code
telos query constraints --file src/auth/mod.rs --json

# Log what you did
telos agent-log \
  --agent claude-review --session sess-042 \
  --operation review \
  --summary "Reviewed auth module for token expiry compliance" \
  --file src/auth/token.rs

Recommended agent workflow:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  1. RECOVER      │────▶│  2. CHECK        │────▶│  3. WORK         │────▶│  4. LOG          │
│                 │     │                 │     │                 │     │                 │
│  telos context  │     │  telos query    │     │  (write code)  │     │  telos decide   │
│  --impact auth  │     │  constraints    │     │                 │     │  telos agent-log│
│  --json         │     │  --file <path>  │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘

Storage Model

graph TD
    HEAD["HEAD"]
    HEAD --> main["main stream"]
    main --> C["Intent C"]
    C --> B["Intent B"]
    B --> A["Intent A (root)"]
    C -.-> D1["DecisionRecord"]
    C -.-> K1["Constraint"]
    K1 -.-> CB1["CodeBinding"]
    B -.-> D2["DecisionRecord"]
    A -.-> BD["BehaviorDiff"]

    style HEAD fill:#f9f,stroke:#333
    style main fill:#bbf,stroke:#333
    style C fill:#bfb,stroke:#333
    style B fill:#bfb,stroke:#333
    style A fill:#bfb,stroke:#333
    style K1 fill:#fbb,stroke:#333
    style CB1 fill:#fbf,stroke:#333

All objects are stored in a content-addressable database:

Serialized to canonical JSON (sorted keys) and hashed with SHA-256
Stored with fan-out: objects/a3/f29c... (2-char prefix + 62-char filename)
Immutable — once written, objects never change
Atomic writes via lockfile mechanism
Prefix-addressable (minimum 4 characters, auto-disambiguated)

Testing

cargo test

102 tests across 4 crates:

Crate	Tests	Coverage
telos-core	20 unit	Object serialization, round-trips, hashing
telos-store	34 unit	ODB, refs, indexes, queries, repository, integrity validation
telos-cli	6 unit + 38 integration	Sync logic, full CLI workflows, changeset commands
telos-experiment	4 unit	Scenario loading, prompt rendering

Roadmap

Phase	Status	Scope
Phase 1	Complete	Core data model, content-addressable storage, CLI, query system, `--json`, `context`
Phase 2	Complete	Constraint lifecycle, code bindings, agent operation logging, IndexStore, code-aware queries
Phase 2.5	Complete	Terminal visualization (`impact`, `graph`, `coverage`, `timeline`), agent sync (`sync`)
Phase 3	Planned	Agent memory SDK (`telos-agent`), semantic search, embedding store
Phase 4	Planned	Deep Git integration (hooks, commit metadata), code graph (`telos-codegraph` + tree-sitter)

See docs/TELOS_V2_DESIGN.md for the full v2 design document.

Contributing

Fork the repository
Create a feature branch: git checkout -b my-feature

Run checks:

cargo fmt --check
cargo clippy -- -D warnings
cargo test

Submit a pull request

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
assets		assets
crates		crates
docs		docs
tests/integration		tests/integration
validation		validation
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Motivation

What is Telos?

Why Telos over flat files?

Quick Start

Build from source

Basic workflow

Core Concepts

Architecture

CLI Reference

For AI Agents

Storage Model

Testing

Roadmap

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Motivation

What is Telos?

Why Telos over flat files?

Quick Start

Build from source

Basic workflow

Core Concepts

Architecture

CLI Reference

For AI Agents

Storage Model

Testing

Roadmap

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages