Git history for AI agents.
Demo: docs/assets/git-aware-coding-agent.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 │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Avos Memory Layer │
│ Repository Memory │
│ ├── PRs & commits │
│ ├── issues & comments │
│ ├── documentation │
│ └── historical context │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agents retrieve context before reasoning │
│ or modifying code │
└─────────────────────────────────────────────────────────────────┘
Works with Claude Code, Cursor, and the terminal. Python 3.10+. Apache-2.0.
# Install (PyPI package name). After install, use the avos CLI everywhere below.
pip install git_aware_coding_agent
# 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
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
- 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.
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?"New engineers or agents can understand the trajectory of the codebase.
avos ask "What is this subsystem responsible for?"
avos history "retry flow"| 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 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 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-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 ingest-pr org/repo 456avos_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 |
OPENAI_API_KEY |
ask, history |
OpenAI API key for LLM synthesis (default provider) |
ANTHROPIC_API_KEY |
ask, history |
Use when AVOS_LLM_PROVIDER=anthropic or config says so |
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/git-aware-coding-agent.git
cd git-aware-coding-agent
pip install -e ".[dev]"
# Run tests
pytest
# Lint and type check
ruff check avos_cli/
mypy avos_cli/Coverage target: 90%+ (enforced in CI).
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