{"id":45866186,"url":"https://github.com/socket-link/ampere","last_synced_at":"2026-05-23T18:01:36.105Z","repository":{"id":209590228,"uuid":"724331833","full_name":"socket-link/ampere","owner":"socket-link","description":"Observable AI cognition in Kotlin Multiplatform. Every agent decision emits a structured event — peer into the glass brain.","archived":false,"fork":false,"pushed_at":"2026-05-17T08:12:31.000Z","size":8311,"stargazers_count":35,"open_issues_count":8,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-17T10:24:17.960Z","etag":null,"topics":["aaif","agent-orchestration","ai-agents","ai-observability","android","anthropic","cognitive-architecture","glass-brain","ios","jvm","kotlin","kotlin-multiplatform","llm","mcp","multi-agent","observable-ai","openai"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/socket-link.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-11-27T21:34:49.000Z","updated_at":"2026-05-17T08:12:34.000Z","dependencies_parsed_at":"2023-12-19T01:52:50.884Z","dependency_job_id":"8e3bebfe-47c1-4aaa-94b6-aa9c9f395930","html_url":"https://github.com/socket-link/ampere","commit_stats":{"total_commits":46,"total_committers":3,"mean_commits":"15.333333333333334","dds":"0.34782608695652173","last_synced_commit":"278ae0cbc898a98577fbaa0e5eb806d00d98e524"},"previous_names":["molmsted98/koreai","socket-link/kore-ai","socket-link/ampere"],"tags_count":9,"template":false,"template_full_name":"JetBrains/compose-multiplatform-template","purl":"pkg:github/socket-link/ampere","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socket-link%2Fampere","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socket-link%2Fampere/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socket-link%2Fampere/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socket-link%2Fampere/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/socket-link","download_url":"https://codeload.github.com/socket-link/ampere/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socket-link%2Fampere/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33406444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aaif","agent-orchestration","ai-agents","ai-observability","android","anthropic","cognitive-architecture","glass-brain","ios","jvm","kotlin","kotlin-multiplatform","llm","mcp","multi-agent","observable-ai","openai"],"created_at":"2026-02-27T08:44:13.387Z","updated_at":"2026-05-23T18:01:36.099Z","avatar_url":"https://github.com/socket-link.png","language":"Kotlin","funding_links":[],"categories":["人工智能"],"sub_categories":["Spring Cloud框架"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ⚡ AMPERE\n\n**Peer into your AI's glass brain.**\n\n[![Maven Central](https://img.shields.io/maven-central/v/link.socket/ampere-core)](https://central.sonatype.com/artifact/link.socket/ampere-core)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Build](https://github.com/socket-link/ampere/actions/workflows/ci.yml/badge.svg)](https://github.com/socket-link/ampere/actions/workflows/ci.yml)\n\n\u003c/div\u003e\n\nAmpere 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.\n\nWhen 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.\n\n---\n\n## Quick Start\n\n\u003e **Prerequisites:** Java 21+ (run `java -version` to check)\n\n### Run agents from the command line (`ampere-cli`)\n\n#### Build CLI\n```bash\n# \u003c!--- Option 1: Installation from source ---\u003e\n#\n# 1. Clone the project\ngit clone https://github.com/socket-link/ampere.git\ncd ampere\n\n# 2. Configure LLM provider API keys in `local.properties`\ncp ampere-cli/local.properties.example ampere-cli/local.properties\nnano ampere-cli/local.properties\n\n# 3. Build the CLI\n./gradlew :ampere-cli:installDist\n\n# 4. Add `ampere` to your PATH for easy access from your project\nexport PATH=\"$PATH:$(pwd)/ampere-cli/build/install/ampere-jvm/bin\"\n\n\n# \u003c!--- Option 2: Install prebuilt binaries ---\u003e\n#\n# Coming soon!\n```\n\n#### Configure Project\n```bash\n# 1. Copy the example `ampere.yaml` config into your \u003cproject\u003e directory\ncp ampere/ampere.example.yaml \u003cproject\u003e/ampere.yaml\n\n# 2. Make any necessary adjustments to the default agent configuration\nnano \u003cproject\u003e/ampere.yaml\n```\n\n**[All Configuration Options →](ampere-cli/README.md#configuration)**\n\n\n#### Start Ampere\n\n```bash\n# Runs Ampere with a goal — this launches the TUI, and agents begin to communicate\ncd \u003cproject\u003e\nampere --goal \"Add comprehensive documentation with interactive examples\"\n```\n\nThe dashboard then displays all agent cognition in real time: perception, recall, optimization, planning, execution, and coordination.\n\nTo change focus between panes in the CLI, press\n- `d` for runtime overview\n- `e` for event stream\n- `m` for agent memory\n\nPress  `?` for more options.\n\n**[Full Usage Guide →](ampere-cli/README.md)**\n\n### Embed in your Kotlin project (`ampere-core`)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDependency Setup\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your project:\n\n```kotlin\n// build.gradle.kts\ndependencies {\n    implementation(\"link.socket:ampere-core:0.1.1\")\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLibrary Usage\u003c/strong\u003e\u003c/summary\u003e\n\n```kotlin\nval team = AgentTeam.create {\n    // Configure your AI provider\n    config(\n        AnthropicConfig(\n            apiKey = System.getenv(\"ANTHROPIC_API_KEY\"),\n            model = Claude.Sonnet4,\n        ),\n    )\n\n    // Add agents with personality traits\n    agent(ProductManager) { personality { directness = 0.8 } }\n    agent(Engineer) { personality { creativity = 0.7 } }\n    agent(QATester)\n}\n\n// Assign a goal and observe the event stream\nteam.goal(\"Build a user authentication system\")\n\nteam.events.collect { event -\u003e\n    when (event) {\n        is Perceived -\u003e println(\"${event.agent} noticed: ${event.signal}\")\n        is Recalled -\u003e println(\"${event.agent} remembered: ${event.memory}\")\n        is Planned -\u003e println(\"${event.agent} decided: ${event.plan}\")\n        is Executed -\u003e println(\"${event.agent} did: ${event.action}\")\n        is Escalated -\u003e println(\"${event.agent} needs help: ${event.reason}\")\n    }\n}\n```\n\n`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.\n\u003c/details\u003e\n\n---\n\n## Why Ampere?\n\nMost agent frameworks bolt on observability after the fact — attaching tools like LangSmith or Langfuse to reconstruct behavior from traces.\n\nAmpere 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.\n\n| Post-hoc Observability                    | Ampere Observability                     |\n|-------------------------------------------|------------------------------------------|\n| Reconstruct behavior from traces          | Decisions are observable as they form    |\n| Observe from outside the agent            | Cognition emits structured events        |\n| Uncertainty hidden in token probabilities | Uncertainty surfaces and escalates       |\n| Memory is an implementation detail        | Memory operations are first-class events |\n\nWhen 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.\n\nThis allows you to steer the agent toward an informed decision in real-time, rather than needing to debug opaque failures after the fact.\n\n## Coordination Primitives\n\n| Concept       | Observable Surface         | Purpose                              |\n|---------------|----------------------------|--------------------------------------|\n| **Tickets**   | Goals and their lifecycle  | Track work from creation to close    |\n| **Tasks**     | Discrete execution steps   | Trace every action an agent performs |\n| **Plans**     | Structured decision logic  | Inspect reasoning before execution   |\n| **Meetings**  | Inter-agent coordination   | Audit how agents negotiate and align |\n| **Outcomes**  | Execution results          | Query historical performance         |\n| **Knowledge** | Accumulated understanding  | Search what agents have learned      |\n\n**[Core Concepts Guide →](docs/CORE_CONCEPTS.md)**\n\n## The PROPEL Cognitive Loop\n\nDuring each timestep of the environment simulation, each agent executes its own independent cognitive cycle:\n\n```\n1. Perceive  ──▶  2. Recall  ──▶  3. Optimize\n\n       ▲                               │\n       │                               ▼\n\n    6. Loop  ◀──  5. Execute  ◀──  4. Plan\n```\n\n| # | Phase          | Operation                           | Emitted Events                         |\n|---|----------------|-------------------------------------|----------------------------------------|\n| 1 | **(P)erceive** | Ingest signals from the environment | `SignalReceived`, `PerceptionFormed`   |\n| 2 | **(R)ecall**   | Query relevant memory and context   | `MemoryQueried`, `ContextAssembled`    |\n| 3 | **(O)ptimize** | Prioritize competing objectives     | `ObjectivesRanked`, `ConfidenceScored` |\n| 4 | **(P)lan**     | Select and structure actions        | `PlanCreated`, `TasksDecomposed`       |\n| 5 | **(E)xecute**  | Carry out the plan                  | `ActionTaken`, `ResultObserved`        |\n| 6 | **(L)oop**     | Evaluate results, re-enter cycle    | `OutcomeEvaluated`, `CycleRestarted`   |\n\nEvery phase transition is emitted as an event, ensuring every action inside an agent can be audited and traced.\n\n**[Full Cognitive Lifecycle →](docs/AGENT_LIFECYCLE.md)**\n\n## Full Documentation\n\n| Guide                                      | Description                         |\n|--------------------------------------------|-------------------------------------|\n| [CLI Reference](ampere-cli/README.md)      | Command-line tools                  |\n| [Core Concepts](docs/CORE_CONCEPTS.md)     | The observable cognition primitives |\n| [Concept Cells](docs/concepts/_index.md)   | Per-primitive invariants and rationale |\n| [Agent Lifecycle](docs/AGENT_LIFECYCLE.md) | The PROPEL loop in detail           |\n| [Architecture](docs/ARCS.md)               | System architecture overview        |\n| [Contributing](CONTRIBUTING.md)            | How to contribute to the project    |\n\n---\n\n## Developer setup\n\nAfter cloning the repo, install the optional pre-push hook that warns when a\npush touches files listed under a [concept cell](docs/concepts/_index.md)'s\n`tracked_sources` without updating the concept file:\n\n```bash\n./scripts/install-hooks.sh\n```\n\nThe hook calls `scripts/validate-concepts.sh` and is informational only — it\nnever blocks a push. Re-running the installer is idempotent. To suppress a\nwarning when your change confirms an existing concept, include the trailer\n`Concept-Verified: \u003cConceptName\u003e` in your commit message.\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE.txt](LICENSE.txt) for more details.\n\nCopyright 2026 Miley Chandonnet, Stedfast Softworks LLC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocket-link%2Fampere","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocket-link%2Fampere","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocket-link%2Fampere/lists"}