Ampere is a Kotlin Multiplatform framework where every agent decision emits a structured, queryable event — providing real-time cognition observability around AI actions that is built into the core of the architecture, rather than being bolted-on after the fact.
When Ampere runs multiple agents in parallel, this open architecture allows each agent to observe, coordinate, and react to the reasoning of others as it forms — making multi-agent coordination reactive rather than scripted.
Prerequisites: Java 21+ (run
java -versionto check)
# <!--- Option 1: Installation from source --->
#
# 1. Clone the project
git clone https://github.com/socket-link/ampere.git
cd ampere
# 2. Configure LLM provider API keys in `local.properties`
cp ampere-cli/local.properties.example ampere-cli/local.properties
nano ampere-cli/local.properties
# 3. Build the CLI
./gradlew :ampere-cli:installDist
# 4. Add `ampere` to your PATH for easy access from your project
export PATH="$PATH:$(pwd)/ampere-cli/build/install/ampere-jvm/bin"
# <!--- Option 2: Install prebuilt binaries --->
#
# Coming soon!# 1. Copy the example `ampere.yaml` config into your <project> directory
cp ampere/ampere.example.yaml <project>/ampere.yaml
# 2. Make any necessary adjustments to the default agent configuration
nano <project>/ampere.yaml# Runs Ampere with a goal — this launches the TUI, and agents begin to communicate
cd <project>
ampere --goal "Add comprehensive documentation with interactive examples"The dashboard then displays all agent cognition in real time: perception, recall, optimization, planning, execution, and coordination.
To change focus between panes in the CLI, press
dfor runtime overviewefor event streammfor agent memory
Press ? for more options.
Dependency Setup
Add to your project:
// build.gradle.kts
dependencies {
implementation("link.socket:ampere-core:0.1.1")
}Library Usage
val team = AgentTeam.create {
// Configure your AI provider
config(
AnthropicConfig(
apiKey = System.getenv("ANTHROPIC_API_KEY"),
model = Claude.Sonnet4,
),
)
// Add agents with personality traits
agent(ProductManager) { personality { directness = 0.8 } }
agent(Engineer) { personality { creativity = 0.7 } }
agent(QATester)
}
// Assign a goal and observe the event stream
team.goal("Build a user authentication system")
team.events.collect { event ->
when (event) {
is Perceived -> println("${event.agent} noticed: ${event.signal}")
is Recalled -> println("${event.agent} remembered: ${event.memory}")
is Planned -> println("${event.agent} decided: ${event.plan}")
is Executed -> println("${event.agent} did: ${event.action}")
is Escalated -> println("${event.agent} needs help: ${event.reason}")
}
}apiKey is optional. When you provide it, Ampere uses that runtime credential directly. When you omit it, provider clients fall back to the generated KotlinConfig values sourced from local.properties at build time.
Most agent frameworks bolt on observability after the fact — attaching tools like LangSmith or Langfuse to reconstruct behavior from traces.
Ampere inverts this. Every cognitive phase emits structured events as a natural consequence of its architecture. This isn't just for debugging — it's what enables agents to coordinate. When Agent B can observe Agent A's reasoning as it forms, coordination becomes reactive rather than scripted.
| Post-hoc Observability | Ampere Observability |
|---|---|
| Reconstruct behavior from traces | Decisions are observable as they form |
| Observe from outside the agent | Cognition emits structured events |
| Uncertainty hidden in token probabilities | Uncertainty surfaces and escalates |
| Memory is an implementation detail | Memory operations are first-class events |
When agent confidence for a plan drops below a configurable threshold, agents are able to escalate to a human, surfacing exactly what they're uncertain about.
This allows you to steer the agent toward an informed decision in real-time, rather than needing to debug opaque failures after the fact.
| Concept | Observable Surface | Purpose |
|---|---|---|
| Tickets | Goals and their lifecycle | Track work from creation to close |
| Tasks | Discrete execution steps | Trace every action an agent performs |
| Plans | Structured decision logic | Inspect reasoning before execution |
| Meetings | Inter-agent coordination | Audit how agents negotiate and align |
| Outcomes | Execution results | Query historical performance |
| Knowledge | Accumulated understanding | Search what agents have learned |
During each timestep of the environment simulation, each agent executes its own independent cognitive cycle:
1. Perceive ──▶ 2. Recall ──▶ 3. Optimize
▲ │
│ ▼
6. Loop ◀── 5. Execute ◀── 4. Plan
| # | Phase | Operation | Emitted Events |
|---|---|---|---|
| 1 | (P)erceive | Ingest signals from the environment | SignalReceived, PerceptionFormed |
| 2 | (R)ecall | Query relevant memory and context | MemoryQueried, ContextAssembled |
| 3 | (O)ptimize | Prioritize competing objectives | ObjectivesRanked, ConfidenceScored |
| 4 | (P)lan | Select and structure actions | PlanCreated, TasksDecomposed |
| 5 | (E)xecute | Carry out the plan | ActionTaken, ResultObserved |
| 6 | (L)oop | Evaluate results, re-enter cycle | OutcomeEvaluated, CycleRestarted |
Every phase transition is emitted as an event, ensuring every action inside an agent can be audited and traced.
| Guide | Description |
|---|---|
| CLI Reference | Command-line tools |
| Core Concepts | The observable cognition primitives |
| Agent Lifecycle | The PROPEL loop in detail |
| Architecture | System architecture overview |
| Contributing | How to contribute to the project |
Apache 2.0 — see LICENSE.txt for more details.
Copyright 2026 Miley Chandonnet, Stedfast Softworks LLC