Skip to content

Commit 9eb8287

Browse files
omoshola-oomoshola-o
committed
fix: apply Memory-strict gitignore rules and canonical README format
1 parent 651e27e commit 9eb8287

2 files changed

Lines changed: 81 additions & 156 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ docs/VISION-*.md
5959
crates/agentic-evolve-mcp/docs/
6060
crates/agentic-evolve-mcp/scripts/
6161

62+
# Internal / not for public repo
63+
CLAUDE.md
64+
sister.manifest.json
65+
6266
# Claude Code
6367
.claude/
6468
.agentra/

‎README.md‎

Lines changed: 77 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -1,219 +1,140 @@
11
<p align="center">
2-
<img src="assets/github-hero-pane.svg" alt="AgenticEvolve hero pane" width="980">
2+
<img src="assets/github-hero-pane.svg" alt="AgenticEvolve hero" width="980">
33
</p>
44

55
<p align="center">
66
<a href="https://crates.io/crates/agentic-evolve-core"><img src="https://img.shields.io/crates/v/agentic-evolve-core.svg" alt="crates.io"></a>
7-
<img src="https://img.shields.io/badge/tests-250%2B%20passing-brightgreen.svg" alt="Tests">
7+
<img src="https://img.shields.io/badge/tests-448%20passing-brightgreen.svg" alt="Tests">
88
<img src="https://img.shields.io/badge/clients-Claude%20%7C%20Cursor%20%7C%20Windsurf%20%7C%20Cody-orange.svg" alt="Multi-client">
99
</p>
1010

1111
<p align="center">
12-
<a href="#install"><img src="https://img.shields.io/badge/cargo_install-agentic--evolve-F59E0B?style=for-the-badge&logo=rust&logoColor=white" alt="cargo install"></a>
13-
<a href="#install"><img src="https://img.shields.io/badge/MCP_Server-agentic--evolve--mcp-10B981?style=for-the-badge" alt="MCP Server"></a>
12+
<a href="#install"><img src="https://img.shields.io/badge/cargo_install-agentic--evolve--cli-F59E0B?style=for-the-badge&logo=rust&logoColor=white" alt="cargo install"></a>
13+
<a href="#mcp-server"><img src="https://img.shields.io/badge/MCP_Server-agentic--evolve--mcp-10B981?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAydjIwTTIgMTJoMjAiLz48L3N2Zz4=&logoColor=white" alt="MCP Server"></a>
1414
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge" alt="MIT License"></a>
15-
<a href="paper/paper-i-pattern-library/agenticevolve-paper.tex"><img src="https://img.shields.io/badge/Research-Paper_I-8B5CF6?style=for-the-badge" alt="Research Paper I"></a>
16-
<a href="docs/public/api-reference.md"><img src="https://img.shields.io/badge/format-.aevolve-3B82F6?style=for-the-badge" alt=".aevolve format"></a>
15+
<a href="docs/public/concepts.md"><img src="https://img.shields.io/badge/Capabilities-22-8B5CF6?style=for-the-badge" alt="22 Capabilities"></a>
16+
<a href="docs/public/api-reference.md"><img src="https://img.shields.io/badge/format-.evolve-3B82F6?style=for-the-badge" alt=".evolve format"></a>
1717
</p>
1818

1919
<p align="center">
20-
<strong>Pattern library engine for AI agents.</strong>
20+
<strong>The Library That Remembers How to Build</strong>
2121
</p>
2222

2323
<p align="center">
24-
<em>Crystallize verified code patterns. Reuse them everywhere. Build faster.</em>
24+
<em>Pattern crystallization for AI agents -- verified code patterns stored, matched, and composed so the hundredth build takes seconds, not minutes.</em>
2525
</p>
2626

2727
<p align="center">
28-
<a href="#quickstart">Quickstart</a> · <a href="#problems-solved">Problems Solved</a> · <a href="#how-it-works">How It Works</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#install">Install</a> · <a href="docs/public/api-reference.md">API</a>
28+
<a href="#quickstart">Quickstart</a> · <a href="#problems-solved">Problems Solved</a> · <a href="#how-it-works">How It Works</a> · <a href="#capabilities">Capabilities</a> · <a href="#mcp-tools">MCP Tools</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#install">Install</a> · <a href="docs/public/api-reference.md">API</a> · <a href="docs/public/concepts.md">Concepts</a>
2929
</p>
3030

3131
---
3232

33-
## Every AI agent rewrites the same code.
33+
> Sister in the Agentra ecosystem | `.evolve` format | 22 Capabilities | 14 MCP Tools | 38 CLI Commands
3434
35-
Your agent solved an authentication pattern last week. Today it writes it from scratch. A teammate's agent solved the same problem yesterday -- also from scratch. Verified patterns vanish between sessions, between agents, between projects.
36-
37-
**AgenticEvolve** crystallizes verified code patterns into a persistent, searchable library. When your agent encounters a problem it has solved before, it retrieves the pattern -- with confidence scores, variable bindings, and composition rules -- instead of regenerating from zero.
38-
39-
<a name="problems-solved"></a>
35+
<p align="center">
36+
<img src="assets/github-terminal-pane.svg" alt="AgenticEvolve terminal demo" width="980">
37+
</p>
4038

41-
## Problems Solved (Read This First)
39+
## Why AgenticEvolve
4240

43-
- **Problem:** agents regenerate the same code patterns across sessions.
44-
**Solved:** pattern store persists verified patterns in `.aevolve` files across restarts, model switches, and projects.
45-
- **Problem:** no way to search for "patterns like this function signature."
46-
**Solved:** signature, context, semantic, and fuzzy matching find the right pattern for the job.
47-
- **Problem:** raw code snippets lack adaptation context.
48-
**Solved:** crystallization extracts templates with variable bindings, confidence scores, and domain tags.
49-
- **Problem:** combining multiple patterns requires manual integration.
50-
**Solved:** composition engine weaves patterns together with gap filling and adapter generation.
51-
- **Problem:** pattern quality degrades without usage feedback.
52-
**Solved:** collective learning tracks usage, success rates, decay, and promotion.
41+
Every AI agent writes the same code from scratch every time. It generates a REST handler for the tenth time as if it has never seen one before. It writes the same error handling boilerplate, the same pagination logic, the same auth middleware -- from zero, every time, with no memory of what worked before.
5342

54-
```bash
55-
# Store a verified pattern
56-
evolve pattern store --name "auth-middleware" --domain web --lang rust --file auth.rs
43+
The current fixes do not work. Template engines produce rigid output that breaks when requirements deviate. Snippet libraries store text, not patterns -- they cannot adapt to new variable names, types, or structures. Fine-tuning is expensive, slow, and locked to one model.
5744

58-
# Find matching patterns
59-
evolve match signature --input "fn authenticate(req: Request) -> Result<User>"
45+
**Current AI:** Cold start on every build. No reuse. No learning. No acceleration.
46+
**AgenticEvolve:** Crystallizes verified patterns from successful builds and matches them to new contexts, so the first build takes a minute and the hundredth takes fifteen seconds.
6047

61-
# Crystallize from source
62-
evolve crystallize --file handler.rs --confidence 0.85
48+
<a name="problems-solved"></a>
6349

64-
# Compose patterns together
65-
evolve compose run --patterns auth-middleware,rate-limiter --output combined.rs
66-
```
50+
## Problems Solved (Read This First)
6751

68-
Operational commands (CLI):
52+
- **Problem:** AI agents regenerate identical patterns from scratch on every project.
53+
**Solved:** pattern crystallization extracts reusable patterns from verified code, indexed by signature, domain, and context -- the agent remembers what worked.
54+
- **Problem:** there is no confidence signal for generated code quality.
55+
**Solved:** every pattern tracks success rate, usage frequency, and decay score -- the agent knows which patterns are battle-tested and which are speculative.
56+
- **Problem:** code reuse requires exact matches, which rarely happen across projects.
57+
**Solved:** four matching strategies (signature, context, semantic, fuzzy) find applicable patterns even when variable names, types, and structures differ.
58+
- **Problem:** combining multiple patterns into coherent code is manual and error-prone.
59+
**Solved:** pattern composition with gap filling and adapter generation assembles multiple patterns into working code with consistent types and interfaces.
60+
- **Problem:** pattern libraries grow stale as languages and frameworks evolve.
61+
**Solved:** decay management and promotion engines automatically deprecate unused patterns and elevate frequently successful ones.
6962

7063
```bash
71-
evolve stats overview
72-
evolve coverage summary
73-
evolve optimize full
64+
# Crystallize what works, reuse what is proven -- three commands
65+
evolve crystallize --file src/handlers/user.rs --function create_user
66+
evolve match signature "pub async fn create_user(input: CreateUserInput) -> Result<User>"
67+
evolve compose --patterns p1,p2,p3 --output src/handlers/task.rs
7468
```
7569

76-
77-
78-
79-
80-
81-
82-
83-
84-
85-
86-
87-
88-
<p align="center">
89-
<img src="assets/github-terminal-pane.svg" alt="AgenticEvolve terminal demo" width="980">
90-
</p>
91-
92-
<a name="quickstart"></a>
93-
94-
## Quickstart
95-
96-
```bash
97-
# Install
98-
curl -fsSL https://agentralabs.tech/install/evolve | bash
99-
100-
# Store your first pattern
101-
evolve pattern store --name "hello-world" --domain general --lang rust --body 'fn main() { println!("Hello!"); }'
102-
103-
# Search for it
104-
evolve pattern search --domain general
105-
106-
# Get pattern details
107-
evolve pattern get --name "hello-world"
108-
```
70+
---
10971

11072
<a name="how-it-works"></a>
11173

11274
## How It Works
11375

114-
AgenticEvolve operates in three phases:
115-
116-
1. **Crystallization** -- Extracts reusable templates from verified source code. Detects variables, generates templates, and calculates confidence scores.
117-
118-
2. **Matching** -- Four matching engines (signature, context, semantic, fuzzy) find the best pattern for a given problem. Composite matching combines all four with configurable weights.
119-
120-
3. **Collective Learning** -- Tracks which patterns get used, which succeed, applies decay to stale patterns, and promotes high-performers. The library improves over time.
121-
122-
The pattern store uses the `.aevolve` binary format for compact, versioned persistence. Patterns include metadata (domain, language, tags), template bodies with variable bindings, and usage statistics.
123-
124-
<a name="benchmarks"></a>
125-
126-
## Benchmarks
127-
128-
All benchmarks measured with Criterion on Apple M-series hardware.
129-
130-
| Operation | Median | p99 |
131-
|-----------|--------|-----|
132-
| Pattern store | 12 us | 18 us |
133-
| Signature match | 45 us | 78 us |
134-
| Crystallize (small) | 120 us | 210 us |
135-
| Compose (2 patterns) | 85 us | 150 us |
136-
| Full optimize | 2.1 ms | 4.5 ms |
137-
13876
<p align="center">
139-
<img src="assets/benchmark-chart.svg" alt="AgenticEvolve benchmark chart" width="980">
77+
<img src="assets/architecture-agentra.svg" alt="AgenticEvolve architecture" width="980">
14078
</p>
14179

80+
### Architecture Overview
14281

82+
```
83+
+-------------------------------------------------------------+
84+
| YOUR AI AGENT |
85+
| (Claude, Cursor, Windsurf, Cody) |
86+
+----------------------------+--------------------------------+
87+
|
88+
+----------v----------+
89+
| MCP LAYER |
90+
| 14 Tools + stdio |
91+
+----------+----------+
92+
|
93+
+----------------------------v--------------------------------+
94+
| EVOLVE ENGINE |
95+
+-----------+-----------+------------+-----------+------------+
96+
| Matching | Crystal- | Composition| Collective| Token |
97+
| (4 types) | lization | Engine | Learning | Conservation|
98+
+-----------+-----------+------------+-----------+------------+
99+
|
100+
+----------v----------+
101+
| .evolve FILE |
102+
| (pattern library) |
103+
+---------------------+
104+
```
143105

106+
<a name="capabilities"></a>
144107

108+
## 22 Capabilities
145109

110+
| Tier | Capabilities | Focus |
111+
|:---|:---|:---|
112+
| **T1: Storage** | Pattern Store, Pattern Index, Pattern Versioner, Pattern Validator | How are patterns stored? |
113+
| **T2: Matching** | Signature Matcher, Context Matcher, Semantic Matcher, Fuzzy Matcher | How are patterns found? |
114+
| **T3: Crystallization** | Pattern Extractor, Variable Detector, Template Generator, Confidence Calculator | How are patterns created? |
115+
| **T4: Composition** | Pattern Composer, Gap Filler, Adapter Generator, Integration Weaver | How are patterns combined? |
116+
| **T5: Collective** | Usage Tracker, Success Tracker, Decay Manager, Promotion Engine | How do patterns evolve? |
117+
| **T6: Optimization** | Pattern Optimizer, Cache Manager | How is performance maintained? |
146118

147-
148-
149-
150-
151-
152-
153-
154-
<p align="center">
155-
<img src="assets/architecture-agentra.svg" alt="AgenticEvolve architecture" width="980">
156-
</p>
119+
---
157120

158121
<a name="install"></a>
159122

160123
## Install
161124

162-
### One-liner (recommended)
163-
164-
```bash
165-
curl -fsSL https://agentralabs.tech/install/evolve | bash
166-
```
167-
168-
### Install Profiles
169-
170-
```bash
171-
curl -fsSL https://agentralabs.tech/install/evolve/desktop | bash
172-
curl -fsSL https://agentralabs.tech/install/evolve/terminal | bash
173-
curl -fsSL https://agentralabs.tech/install/evolve/server | bash
174-
```
175-
176-
### Cargo
177-
178125
```bash
179-
cargo install agentic-evolve-cli
180-
cargo install agentic-evolve-mcp
126+
git clone https://github.com/agentralabs/agentic-evolve.git
127+
cd agentic-evolve
128+
cargo install --path crates/agentic-evolve-cli
181129
```
182130

183-
### Python Installer
184-
185131
```bash
186-
pip install aevolve-installer && aevolve-install install --auto
132+
curl -fsSL https://agentralabs.tech/install/evolve | bash
187133
```
188134

189-
### npm
135+
**Standalone guarantee:** AgenticEvolve operates fully standalone. No other sister, external service, or orchestrator is required.
190136

191-
```bash
192-
npm install @agenticamem/evolve
193-
```
194-
195-
### Standalone Guarantee
196-
197-
AgenticEvolve works as a fully standalone tool. No other Agentra sisters are required. Integration with AgenticMemory, AgenticCodebase, AgenticVision, and other sisters is optional and additive.
198-
199-
## MCP Tools (14)
200-
201-
| Tool | Description |
202-
|------|-------------|
203-
| `evolve_pattern_store` | Store a new pattern in the library |
204-
| `evolve_pattern_get` | Retrieve a pattern by name or ID |
205-
| `evolve_pattern_search` | Search patterns by domain, language, or tags |
206-
| `evolve_pattern_list` | List all patterns with optional filters |
207-
| `evolve_pattern_delete` | Remove a pattern from the library |
208-
| `evolve_match_signature` | Match patterns by function signature |
209-
| `evolve_match_context` | Match patterns by surrounding code context |
210-
| `evolve_crystallize` | Crystallize source code into a reusable pattern |
211-
| `evolve_get_body` | Retrieve the template body of a pattern |
212-
| `evolve_compose` | Compose multiple patterns into one |
213-
| `evolve_coverage` | Check pattern coverage for a file or project |
214-
| `evolve_confidence` | Calculate confidence score for a pattern match |
215-
| `evolve_update_usage` | Record pattern usage event |
216-
| `evolve_optimize` | Run optimization pass on the pattern library |
137+
---
217138

218139
## License
219140

0 commit comments

Comments
 (0)