Skip to content

Commit 307913d

Browse files
George-iamGeorge-iam
committed
docs: README iteration - dark diagram, reorganize sections, trim footer
1. Diagram back to dark theme 2. Components section moved to collapsible at bottom 3. Knowledge Categories moved up (between What You Get and How It Works) 4. Preset Bundles moved to collapsible 5. Development section removed 6. Related trimmed to axme only 7. Security/License links removed from footer (broken)
1 parent c9840e9 commit 307913d

3 files changed

Lines changed: 45 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 44 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -61,27 +61,22 @@ Each repo has its own knowledge base (`.axme-code/`). Workspace-level rules appl
6161

6262
---
6363

64-
## How It Works
65-
66-
![AXME Code Overview](docs/diagrams/axme-code-overview.png)
67-
68-
AXME Code has three components:
69-
70-
### 1. MCP Server (persistent, runs while VS Code is open)
71-
72-
Provides tools for the agent to read and write the knowledge base. All writes go through MCP server code (atomicWrite, correct append) - the agent never writes storage files directly. This guarantees format consistency.
73-
74-
### 2. Hooks (fire on every tool call)
64+
## Knowledge Categories
7565

76-
**pre-tool-use**: Checks every Bash command, git operation, and file access against safety rules. Blocks violations before they execute. Also creates/recovers session tracking.
66+
| Category | What it stores | Example |
67+
|----------|---------------|---------|
68+
| **Oracle** | Project structure, tech stack, coding patterns, glossary | "Python 3.11, FastAPI, PostgreSQL" |
69+
| **Decisions** | Architectural decisions with enforcement levels (required/advisory) | "All deploys via GitHub Actions only" (required) |
70+
| **Memory** | Feedback from mistakes, validated patterns | "Never use sync httpx in async handlers" |
71+
| **Safety** | Protected branches, denied commands, filesystem restrictions | git push --force -> BLOCKED |
72+
| **Handoff** | Where work stopped, blockers, next steps | "PR#17 open, needs review" |
73+
| **Worklog** | Session history, audit results, events | Timeline of all sessions |
7774

78-
**post-tool-use**: Records which files the agent changed (for audit trail).
75+
---
7976

80-
### 3. Background Auditor (runs after session close)
77+
## How It Works
8178

82-
A detached process that reads the session transcript and catches anything the agent forgot to save. Two modes:
83-
- **Full extraction** - when the agent crashed or the user closed the window without formal close
84-
- **Verify-only** - when the agent completed the close checklist (lighter, cheaper)
79+
![AXME Code Overview](docs/diagrams/axme-code-overview.png)
8580

8681
### Session Flow
8782

@@ -116,40 +111,38 @@ All data lives in `.axme-code/` in your project root (or workspace root for mult
116111
config.yaml # Model settings, presets
117112
```
118113

119-
### Knowledge Categories
114+
---
120115

121-
| Category | What it stores | Example |
122-
|----------|---------------|---------|
123-
| **Oracle** | Project structure, tech stack, coding patterns, glossary | "Python 3.11, FastAPI, PostgreSQL" |
124-
| **Decisions** | Architectural decisions with enforcement levels (required/advisory) | "All deploys via GitHub Actions only" (required) |
125-
| **Memory** | Feedback from mistakes, validated patterns | "Never use sync httpx in async handlers" |
126-
| **Safety** | Protected branches, denied commands, filesystem restrictions | git push --force -> BLOCKED |
127-
| **Handoff** | Where work stopped, blockers, next steps | "PR#17 open, needs review" |
128-
| **Worklog** | Session history, audit results, events | Timeline of all sessions |
116+
## Related
117+
118+
| Repository | Description |
119+
|-----------|-------------|
120+
| [axme](https://github.com/AxmeAI/axme) | AXME platform - durable execution for AI agents |
129121

130122
---
131123

132-
## Preset Bundles
124+
<details>
125+
<summary><strong>Components</strong></summary>
133126

134-
During `axme-code setup`, preset bundles provide curated best-practice rules:
127+
AXME Code has three components:
135128

136-
| Preset | What it adds |
137-
|--------|-------------|
138-
| **essential-safety** | Protected branches, no secrets in git, no force push, fail loudly |
139-
| **ai-agent-guardrails** | Verification requirements, no autonomous deploys, proof before done |
129+
### 1. MCP Server (persistent, runs while VS Code is open)
140130

141-
---
131+
Provides tools for the agent to read and write the knowledge base. All writes go through MCP server code (atomicWrite, correct append) - the agent never writes storage files directly. This guarantees format consistency.
142132

143-
## Development
133+
### 2. Hooks (fire on every tool call)
144134

145-
```bash
146-
npm install
147-
npm run build # esbuild -> dist/server.js + dist/cli.mjs
148-
npm test # Node.js test runner (requires Node 22+)
149-
npx tsc --noEmit # TypeScript strict type check
150-
```
135+
**pre-tool-use**: Checks every Bash command, git operation, and file access against safety rules. Blocks violations before they execute. Also creates/recovers session tracking.
151136

152-
---
137+
**post-tool-use**: Records which files the agent changed (for audit trail).
138+
139+
### 3. Background Auditor (runs after session close)
140+
141+
A detached process that reads the session transcript and catches anything the agent forgot to save. Two modes:
142+
- **Full extraction** - when the agent crashed or the user closed the window without formal close
143+
- **Verify-only** - when the agent completed the close checklist (lighter, cheaper)
144+
145+
</details>
153146

154147
<details>
155148
<summary><strong>Available MCP Tools</strong></summary>
@@ -190,18 +183,18 @@ axme-code audit-session # Run LLM audit on a session transcript
190183

191184
</details>
192185

193-
---
186+
<details>
187+
<summary><strong>Preset Bundles</strong></summary>
194188

195-
## Related
189+
During `axme-code setup`, preset bundles provide curated best-practice rules:
196190

197-
| Repository | Description |
198-
|-----------|-------------|
199-
| [axme](https://github.com/AxmeAI/axme) | AXME platform - durable execution for AI agents |
200-
| [axme-cli](https://github.com/AxmeAI/axme-cli) | Command-line interface |
201-
| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python SDK |
202-
| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript SDK |
203-
| [axme-docs](https://github.com/AxmeAI/axme-docs) | Documentation |
191+
| Preset | What it adds |
192+
|--------|-------------|
193+
| **essential-safety** | Protected branches, no secrets in git, no force push, fail loudly |
194+
| **ai-agent-guardrails** | Verification requirements, no autonomous deploys, proof before done |
195+
196+
</details>
204197

205198
---
206199

207-
hello@axme.ai | [Security](SECURITY.md) | [License](LICENSE)
200+
hello@axme.ai

‎docs/diagrams/axme-code-overview.png‎

20.2 KB
Loading

0 commit comments

Comments
 (0)