Git history for AI agents.
Demo: docs/assets/avos-dev-cli.gif
Avos gives AI coding agents persistent, queryable memory so they can remember why code exists, what decisions shaped it, and how it was built — before they modify it.
┌─────────────────────────────────────────────────────────────────┐
│ Developer / AI Agent │
│ (Claude Code, Cursor, Terminal) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Avos CLI │
│ connect · ingest · ask · history · session-start · session-end│
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Avos Memory Layer │
├─────────────────────────────┬───────────────────────────────────┤
│ Repository Memory │ Session Memory │
│ ├── PRs & commits │ ├── session goals │
│ ├── issues & comments │ ├── files touched │
│ ├── documentation │ ├── decisions made │
│ └── historical context │ └── audit trail │
└─────────────────────────────┴───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agents retrieve context before reasoning │
│ or modifying code │
└─────────────────────────────────────────────────────────────────┘
Works with Claude Code, Cursor, and the terminal. Python 3.10+. Apache-2.0.
# Install
pip install avos-dev-cli
# Set credentials
export AVOS_API_KEY="your-key"
export GITHUB_TOKEN="your-token"
# Connect your repository
avos connect org/repo
# Ingest history (last 90 days)
avos ingest org/repo --since 90d
# Ask a question
avos ask "Why do we use Kafka here?"That's it. Your repository now has queryable memory.
AI coding agents forget.
They can read the current file tree, but they cannot know:
- why a function exists
- what constraints shaped a module
- which old assumptions still matter
- what happened in previous PRs
- how a feature was implemented across a session
This causes bad rewrites, repeated mistakes, and fragile changes.
Avos attaches portable memory to your repository.
Agents can query this memory before reasoning about code, giving them long-term context about the system — not just the current snapshot.
- Persistent memory across agent sessions
- PR-aware reasoning about past changes
- Queryable knowledge from code, docs, and artifacts
- Traceable decision history for agents
- Audit trails for compliance and accountability
- Portable memory that moves between agents and tools
Stores the durable history of the codebase: PRs, commits, issues, comments, and documentation.
Powers avos ask and avos history.
Stores the working context of each coding session: goal, files touched, decisions, errors, tests run, and remaining risks.
Powers avos session-start, avos session-end, and avos session-ask.
Together, these let you understand both the history of the repository and the audit trail of how a change was built.
Agents can remember previous design decisions and reuse solutions across sessions.
avos ask "Why was retry scheduler added?"
avos history "retry scheduler"Teams can query historical reasoning before modifying old code.
avos ask "What constraints shaped the auth module?"Agents coordinating on complex tasks can share persistent knowledge.
avos session-start "Implement payment retry"
# ... agent works ...
avos session-endNew engineers or agents can understand the trajectory of the codebase.
avos ask "What is this subsystem responsible for?"
avos session-ask "How was this retry flow implemented?"| Command | What it does |
|---|---|
avos connect org/repo |
Attach a repository to Avos Memory |
avos ingest org/repo --since 90d |
Import PRs, issues, commits, and docs into repository memory |
avos ingest-pr org/repo 123 |
Ingest a single PR (after push/merge) |
avos ask "question" |
Search repository memory for evidence-backed answers |
avos history "subject" |
Reconstruct the chronological history of a subsystem or concept |
avos session-start "goal" |
Start a tracked coding session |
avos session-end |
End the session and store the implementation trail |
avos session-status |
Check if a session is currently active |
avos session-ask "question" |
Search session memory for implementation context |
avos worktree-add <path> <branch> "goal" --agent name |
Create a git worktree with auto session start |
avos worktree-init |
Initialize avos in an existing git worktree |
avos hook-install |
Install pre-push hook (auto-installed on connect) |
--json Emit machine-readable JSON (for AI agents and automation)
--verbose Enable debug output
--version Show version
When you connect a repository, avos automatically installs a pre-push git hook that syncs commits to Avos Memory on every git push. This keeps your team's memory up-to-date without manual avos ingest runs.
Every command supports --json for strict machine-readable output:
avos --json session-status
avos --json ask "how does auth work?"
avos --json ingest-pr org/repo 123All JSON responses follow the same envelope:
{
"success": true,
"data": { ... },
"error": null
}On error:
{
"success": false,
"data": null,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message",
"hint": "How to fix it",
"retryable": true
}
}For ask and history, JSON output is produced by LLM converter agents and requires the REPLY_MODEL environment variables. For all other commands, JSON output is deterministic (no LLM dependency).
Avos ships with built-in integration files for AI coding platforms.
.cursor/
├── rules/avos-agent-workflow.mdc # Always-on workflow rules
└── skills/
├── avos-session/SKILL.md # Session lifecycle
├── avos-search/SKILL.md # Memory search with avos ask
├── avos-history/SKILL.md # Chronological history
└── avos-ingest-pr/SKILL.md # Single-PR ingest after push
.claude/
├── CLAUDE.md # Project-level instructions
├── commands/ # Slash commands
├── agents/ # Sub-agents for research/session management
└── instincts/ # Auto-trigger behaviors
.codex/instructions.md # Community stub
.agents/README.md # Integration guide for new platforms
avos ask "why does this function exist?"
avos history "module-or-function-name"avos session-start "Fix retry backoff in payment worker"
# ... do work ...
avos session-endavos ingest-pr org/repo 456Avos supports multiple agents working in parallel via git worktrees:
# Create a worktree with automatic session start
avos worktree-add ../feature-x feature-branch "Implement auth" --agent agentA
# Or initialize an existing worktree
cd ../existing-worktree
avos worktree-init
avos session-start --agent agentB "Build pagination"In a worktree, --agent is required to distinguish parallel sessions.
avos_cli/
├── cli/main.py # Typer CLI entry point
├── commands/ # Orchestrators (one per command)
├── artifacts/ # Builders that produce canonical text for memory
├── services/ # Memory API, GitHub, LLM, citation validator
├── agents/ # LLM prompt templates for output formatting
├── models/ # Pydantic models
├── config/ # State files, hash store, lock manager
└── utils/ # Output formatting, logging
Design principles:
- Each command is an independent orchestrator with constructor DI
- Stateless CLI, stateful memory (via
memory_id) - Graceful degradation: if LLM synthesis fails, fallback to evidence-backed raw output
| Variable | Required for | Description |
|---|---|---|
AVOS_API_KEY |
All commands | Avos Memory API key from https://avoslab.com/ |
AVOS_API_URL |
All commands | API endpoint (default: https://avosmemory.avoslab.com) |
GITHUB_TOKEN |
connect, ingest, ingest-pr |
GitHub personal access token |
ANTHROPIC_API_KEY |
ask, history, session-ask |
Anthropic API key for LLM synthesis |
OPENAI_API_KEY |
ask, history, session-ask |
Alternative: OpenAI API key |
REPLY_MODEL |
--json for ask/history |
Model identifier for output formatting |
REPLY_MODEL_URL |
--json for ask/history |
API endpoint for reply model |
REPLY_MODEL_API_KEY |
--json for ask/history |
API key for reply model |
git clone https://github.com/Avos-Lab/avos-dev-cli.git
cd avos-dev-cli
pip install -e ".[dev]"
# Run tests
pytest
# Lint and type check
ruff check avos_cli/
mypy avos_cli/Coverage target: 90%+ (enforced in CI).
Session memory preserves a searchable trail of who changed what, why, what tests were run, and what risks remained. This is useful for engineering reviews, internal accountability, and regulated environments.
However: Avos is not itself a compliance certification. Session memory is supporting evidence, not a full compliance program.
AI agents will become long-lived collaborators on codebases.
But without memory, they cannot accumulate knowledge. They forget decisions, repeat mistakes, and lose context between sessions.
Avos explores what persistent memory for autonomous agents should look like.
We welcome contributions to the CLI, integrations, and developer workflows.
Areas we're especially interested in:
- New memory connectors
- Retrieval algorithms
- Agent integrations (Codex, OpenCode, etc.)
- Developer tooling
See CONTRIBUTING.md for setup and PR process.
- User Guide — Command reference, troubleshooting
- Contributor Guide — Setup, testing, code style
- Changelog — Release history
- Agent Integration Guide — Adding new platform integrations
Apache-2.0
