agentharmony

Persistent Context for AI Agent Workflows

v0.1.0 Open Source In Development

The Challenge of AI Agent Memory

When working with AI agents on complex engineering projects that span multiple days or weeks, one critical limitation emerges: agents have no persistent memory across sessions. Every time you start a new terminal session, the agent begins with a blank slate, unable to recall the architectural decisions, failed attempts, or hard-won insights from previous conversations.

This limitation forces users to manually re-explain context, repeat documentation, and risk reintroducing bugs that were already solved. For engineers with limited subject matter expertise relying on AI assistance, this memory gap can make complex multi-session projects nearly unsustainable.

agentharmony solves this problem by creating a structured framework that enables AI agents to effectively "remember" everything across sessions—forming what amounts to a conversation between your current agent and all previous agents who worked on the project.

What is agentharmony?

agentharmony is a turnkey starter kit that packages governance documents, project templates, CLI bootstrap scripts, and automation tooling into a reusable framework. It allows any terminal-based AI agent (like Claude Code, GitHub Copilot CLI, or custom agent implementations) to:

Value Proposition

For Engineers Using AI Agents

For Teams & Organizations

Use Cases

1. Solo Developers Building Complex Systems

A developer with limited AWS experience is building a serverless data pipeline. agentharmony lets them pause and resume work across weeks without losing architectural context or re-debugging CloudFormation errors.

2. Multi-Session Debugging Workflows

When troubleshooting a persistent bug, agentharmony logs every hypothesis tested, every configuration change attempted, and every log line analyzed—preventing the agent from suggesting the same failed fix twice.

3. Rapid Prototyping with AI Assistance

Entrepreneurs using AI to prototype MVPs can maintain governance docs that track feature scope, cost constraints, and deployment status—ensuring agents always align with business goals.

4. Knowledge Preservation for Consulting Projects

Consultants can hand off projects to clients with complete documentation auto-generated and maintained by agents throughout development, ensuring seamless post-engagement support.

How It Works: The agentharmony Methodology

Core Principle: External Memory as Persistent Context

agentharmony treats documentation as external memory for AI agents. Rather than relying on the agent's ephemeral session context, critical information is stored in structured files that are automatically loaded at the start of each session.

The Three-Layer Architecture

  1. Governance Layer (agents.md): Defines universal operating principles, preferred technologies, logging standards, and workflow directives that apply across all projects.
  2. Project Layer (<project>-reference.md): Contains project-specific context including architecture, known issues, feature roadmap, and historical decision logs.
  3. Registry Layer (YAML files): Structured data for features, tasks, and bugs with IDs, status tracking, and debug logs—serving as a lightweight project management database.

Automated Session Bootstrap

When you start a new session using codex <project> or claude <project> (via provided CLI wrappers), agentharmony:

  1. Exports the PROJECT environment variable
  2. Streams governance files (agents.md and supporting docs) into the agent's context
  3. Loads project-specific reference documentation and registries
  4. Hands off to the AI agent with full historical context

This entire process completes in under 30 seconds, and the agent immediately knows the project's current status, recent changes, active bugs, and recommended next steps.

Key Components & Features

1. Starter Kit Distribution (repo/src/)

A blank-canvas folder structure containing:

2. Session Bootstrap Automation

3. Documentation Hub

Every project maintains a living reference document that captures:

4. Tooling & Quality Automation

5. Structured Logging & Debug Standards

agentharmony includes a comprehensive logging taxonomy using tags like [START], [SUCCESS], [ERROR], [DEBUG], and [RETRY] to create machine-parseable execution logs that help agents diagnose failures systematically.

Getting Started

Prerequisites

Installation

# Clone the agentharmony repository
git clone https://github.com/me-jreese/agentharmony/tree/main.git
cd agentharmony

# Copy the starter kit to your workspace
cp -R repo/src ~/my-workspace/agentharmony-kit

# Navigate to the kit
cd ~/my-workspace/agentharmony-kit

Quick Setup (New Project)

# 1. Create project directory structure
mkdir -p projects/my-project/agent-reference
mkdir -p projects/my-project/repo

# 2. Copy templates
cp agent-reference-template/$PROJECT-reference-template.md \
   projects/my-project/agent-reference/my-project-reference.md

cp -R repo-template/* projects/my-project/repo/

# 3. Customize projects.yaml
# Edit projects.yaml to add your project entry

# 4. Set up shell aliases (add to ~/.bashrc or ~/.zshrc)
alias codex="/path/to/agentharmony-kit/codex-auto.sh"
alias claude="/path/to/agentharmony-kit/claude-project"

# 5. Start your first session!
codex my-project

Customizing for Your Environment

Update the following placeholder files with your organization's details:

How to Use agentharmony

Daily Workflow

  1. Start a session: Run codex my-project or claude my-project
  2. Review the brief: The agent will summarize current status and recommended next steps based on loaded documentation
  3. Work on tasks: The agent has full context and will autonomously update documentation as work progresses
  4. End the session: Documentation updates are committed; next session picks up seamlessly

When to Update Documentation

agentharmony directs agents to update the reference docs and registries whenever:

Target KPI: Documentation should stay fresh within 24 hours of substantial scope changes.

Avoiding Debugging Loops

When an agent encounters a persistent issue:

  1. It assigns an issue ID (e.g., AGH-ISS-003)
  2. Logs every hypothesis and attempted fix in the debug log
  3. If stuck after multiple attempts, autonomously evaluates alternative approaches
  4. Never retests a solution that was already logged as failed

Best Practices

Roadmap

Current Status (v0.1.0)

Upcoming Features

Get Involved

agentharmony is an open-source project available now. The repository is hosted at:

GitHub: github.com/me-jreese/agentharmony

If you're interested in early access, contributing to the project, or have questions about implementing agentharmony in your workflow, please reach out via the contact methods below.

About the Author

agentharmony was developed by J Reese in November 2025 to address the challenges of managing complex engineering projects with AI assistance. After discovering that limited software experience combined with AI agents could successfully implement sophisticated technical solutions—provided institutional memory was preserved—the framework emerged as a way to simulate "wise memory" across agent sessions.

The methodology has been battle-tested on production systems including multi-service AWS architectures, data pipeline orchestration, and web infrastructure automation.

View on GitHub