substr8 0.7.1
Substr8 Platform CLI - Verifiable AI Infrastructure
Requires Python: >=3.10
Keywords: acc, agents, ai, capability, fdaa, gam, memory, verifiable

# Substr8 CLI

[![PyPI version](https://badge.fury.io/py/substr8.svg)](https://pypi.org/project/substr8/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Verifiable AI Infrastructure** — The command-line interface for the Substr8 platform.

Substr8 provides provable, auditable, and deterministic infrastructure for AI agents. This CLI bundles our core tools:

- **GAM** — Git-Native Agent Memory (cryptographically verifiable memory)
- **FDAA** — File-Driven Agent Architecture (coming soon)
- **ACC** — Agent Capability Control (coming soon)

## Installation

```bash
pip install substr8
```

### Optional Dependencies

```bash
# With cryptographic signing (agent DIDs, GPG integration)
pip install substr8[crypto]

# With semantic search (embeddings-based recall)
pip install substr8[retrieval]

# Everything
pip install substr8[full]
```

## Quick Start

```bash
# Initialize GAM in your workspace
cd your-project
substr8 gam init

# Store a memory
substr8 gam remember "Raza exercises 4-5x per week" --tag health

# Search memories (semantic search)
substr8 gam recall "fitness routine"

# Verify provenance
substr8 gam verify mem_1234567890_abcd

# Show status
substr8 gam status
```

## GAM — Git-Native Agent Memory

GAM uses git's 20-year-old version control primitives to provide:

| Feature | How |
|---------|-----|
| **Cryptographic provenance** | Every memory has a commit SHA |
| **Tamper-evident history** | Merkle tree — change anything, hash breaks |
| **Human-auditable** | Plain Markdown files, `git blame` works |
| **Temporal awareness** | Decay scoring, point-in-time queries |
| **W^X permissions** | Path-based access control with HITL gates |

### Commands

```bash
# Core operations
substr8 gam init              # Initialize repository
substr8 gam remember <text>   # Store a memory
substr8 gam recall <query>    # Search memories
substr8 gam verify <id>       # Verify provenance
substr8 gam forget <id>       # Delete a memory
substr8 gam status            # Show repository status

# Identity management
substr8 gam identity create-agent <name>  # Create agent DID
substr8 gam identity list                 # List identities

# Permissions (W^X)
substr8 gam permissions list    # Show all path policies
substr8 gam permissions check   # Check a specific path
substr8 gam permissions hitl    # Show human-required paths

# Maintenance
substr8 gam import <path>     # Import existing .md files
substr8 gam reindex           # Rebuild indexes
```

### Memory File Format

Memories are stored as Markdown with YAML frontmatter:

```markdown
---
gam_version: 1
id: mem_2026021908001234
created: 2026-02-19T08:00:00Z
source: conversation
confidence: high
tags: [health, fitness]
---

# Raza's Fitness Goals

Raza exercises 4-5x/week and has quit alcohol.
```

### W^X Permissions

| Path | Permission | Signature Required |
|------|------------|-------------------|
| `SOUL.md` | HUMAN_SIGN | Human GPG |
| `AGENTS.md` | HUMAN_SIGN | Human GPG |
| `MEMORY.md` | AGENT_SIGN | Agent DID |
| `memory/daily/*` | OPEN | None |
| `memory/archive/*` | READONLY | N/A |

## Platform Status

```bash
substr8 info
```

```
┌─────────────────────────────────────┐
│         Substr8 Platform v1.0.0     │
├───────────┬──────────┬──────────────┤
│ Component │ Status   │ Description  │
├───────────┼──────────┼──────────────┤
│ GAM       │ ✅ v1.0.0│ Git Memory   │
│ FDAA      │ 🔜       │ File Agents  │
│ ACC       │ 🔜       │ Capabilities │
└───────────┴──────────┴──────────────┘
```

## Research

| Paper | DOI |
|-------|-----|
| GAM: Git-Native Agent Memory | [`10.5281/zenodo.18704573`](https://doi.org/10.5281/zenodo.18704573) |
| ACC: Agent Capability Control | [`10.5281/zenodo.18704577`](https://doi.org/10.5281/zenodo.18704577) |
| FDAA: File-Driven Agent Architecture | [`10.5281/zenodo.18675147`](https://doi.org/10.5281/zenodo.18675147) |

## Links

- **Website:** [substr8labs.com](https://substr8labs.com)
- **Substack:** [substr8labs.substack.com](https://substr8labs.substack.com)
- **GitHub:** [github.com/Substr8-Labs](https://github.com/Substr8-Labs)
- **Twitter:** [@substr8labs](https://twitter.com/substr8labs)

## License

MIT — [Substr8 Labs](https://substr8labs.com)

---

*AI systems should be provable, not just probable.*