# Ampere

> Observable AI cognition in Kotlin Multiplatform. Every agent decision emits a structured event — peer into the glass brain.

- **Type:** MCP server
- **Install:** `agentstack add mcp-socket-link-ampere`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [socket-link](https://agentstack.voostack.com/s/socket-link)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [socket-link](https://github.com/socket-link)
- **Source:** https://github.com/socket-link/ampere

## Install

```sh
agentstack add mcp-socket-link-ampere
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ⚡ AMPERE

**Peer into your AI's glass brain.**

[](https://central.sonatype.com/artifact/link.socket/ampere-core)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/socket-link/ampere/actions/workflows/ci.yml)

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.

---

## Quick Start

> **Prerequisites:** Java 21+ (run `java -version` to check)

### Run agents from the command line (`ampere-cli`)

#### Build CLI
```bash
# 
#
# 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"

# 
#
# Coming soon!
```

#### Configure Project
```bash
# 1. Copy the example `ampere.yaml` config into your  directory
cp ampere/ampere.example.yaml /ampere.yaml

# 2. Make any necessary adjustments to the default agent configuration
nano /ampere.yaml
```

**[All Configuration Options →](ampere-cli/README.md#configuration)**

#### Start Ampere

```bash
# Runs Ampere with a goal — this launches the TUI, and agents begin to communicate
cd 
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
- `d` for runtime overview
- `e` for event stream
- `m` for agent memory

Press  `?` for more options.

**[Full Usage Guide →](ampere-cli/README.md)**

### Embed in your Kotlin project (`ampere-core`)

Dependency Setup

Add to your project:

```kotlin
// build.gradle.kts
dependencies {
    implementation("link.socket:ampere-core:0.1.1")
}
```

Library Usage

```kotlin
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.

---

## Why Ampere?

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.

## Coordination Primitives

| 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      |

**[Core Concepts Guide →](docs/CORE_CONCEPTS.md)**

## The PROPEL Cognitive Loop

During each timestep of the environment simulation, each agent executes its own independent cognitive cycle:

```
1. Perceive  ──▶  2. Recall  ──▶  3. Observe

       ▲                               │
       │                               ▼

    6. Learn  ◀──  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)bserve**  | Read current state and detect drift | `StateObserved`, `DriftDetected`       |
| 4 | **(P)lan**     | Select and structure actions        | `PlanCreated`, `TasksDecomposed`       |
| 5 | **(E)xecute**  | Carry out the plan                  | `ActionTaken`, `ResultObserved`        |
| 6 | **(L)earn**    | Extract knowledge, re-enter cycle   | `OutcomeEvaluated`, `KnowledgeStored`  |

Every phase transition is emitted as an event, ensuring every action inside an agent can be audited and traced.

**[Full Cognitive Lifecycle →](docs/AGENT_LIFECYCLE.md)**

## Full Documentation

| Guide                                      | Description                         |
|--------------------------------------------|-------------------------------------|
| [CLI Reference](ampere-cli/README.md)      | Command-line tools                  |
| [Core Concepts](docs/CORE_CONCEPTS.md)     | The observable cognition primitives |
| [Concept Cells](docs/concepts/_index.md)   | Per-primitive invariants and rationale |
| [Agent Lifecycle](docs/AGENT_LIFECYCLE.md) | The PROPEL loop in detail           |
| [Architecture](docs/ARCS.md)               | System architecture overview        |
| [Contributing](CONTRIBUTING.md)            | How to contribute to the project    |

---

## Developer setup

After cloning the repo, install the optional pre-push hook that warns when a
push touches files listed under a [concept cell](docs/concepts/_index.md)'s
`tracked_sources` without updating the concept file:

```bash
./scripts/install-hooks.sh
```

The hook calls `scripts/validate-concepts.sh` and is informational only — it
never blocks a push. Re-running the installer is idempotent. To suppress a
warning when your change confirms an existing concept, include the trailer
`Concept-Verified: ` in your commit message.

---

## License

Apache 2.0 — see [LICENSE.txt](LICENSE.txt) for more details.

Copyright 2026 Miley Chandonnet, Stedfast Softworks LLC

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [socket-link](https://github.com/socket-link)
- **Source:** [socket-link/ampere](https://github.com/socket-link/ampere)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-socket-link-ampere
- Seller: https://agentstack.voostack.com/s/socket-link
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.