substr8-gam 0.1.0
Git-Native Agent Memory - Verifiable memory for AI agents
Requires Python: >=3.10
Keywords: agents, ai, git, memory, verifiable

# GAM - Git-Native Agent Memory

> Verifiable, auditable memory for AI agents using git primitives.

## Why GAM?

Current AI memory approaches (vector DBs, knowledge graphs) are black boxes. You can't verify when a memory was formed, who created it, or how it evolved. GAM fixes this by using git as the storage layer:

- **Every memory has a commit hash** — cryptographic proof of content
- **Every change is signed** — authentic provenance
- **Full history via git blame** — lineage for every fact
- **Human-readable Markdown** — audit without special tools

## Quick Start

```bash
# Install
pip install gam

# Initialize in any git repo
cd my-agent
gam init

# Remember something
gam remember "Raza prefers morning meetings" --tag scheduling

# Recall memories
gam recall "meeting preferences"

# Verify provenance
gam verify mem_1708344000000_a1b2
```

## Python API

```python
from gam import open_gam, MemoryMetadata

# Open repository
repo = open_gam("/path/to/agent")

# Store a memory
memory = repo.remember(
    content="Raza's fitness goal is marathon-ready by end of year",
    title="Fitness Goals",
    metadata=MemoryMetadata(
        source="conversation",
        confidence="high",
        tags=["health", "goals"],
    )
)

print(f"Stored: {memory.id} at commit {memory.commit_sha}")

# Recall memories
results = repo.recall("fitness goals", limit=5)
for mem in results:
    print(f"{mem.id}: {mem.content[:50]}...")

# Verify
result = repo.verify(memory.id)
print(f"Valid: {result.valid}, Commit: {result.commit_sha}")
```

## Directory Structure

```
your-repo/
├── MEMORY.md                 # Hot tier (always loaded)
├── memory/
│   ├── daily/YYYY-MM-DD.md  # Daily logs
│   ├── topics/*.md          # Topic-organized
│   └── entities/*.md        # People, orgs, projects
└── .gam/
    ├── config.yaml          # Configuration
    └── access.jsonl         # Access log (for decay)
```

## Memory File Format

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

# Raza's Fitness Goals

He's targeting marathon-ready fitness by year end.
Exercises 4-5x/week, quit alcohol.
```

## Installation

```bash
# Basic (keyword search only)
pip install gam

# With semantic search (embeddings)
pip install gam[retrieval]

# Development
pip install gam[dev]
```

## Integration with FDAA

GAM memories can be wrapped as FDAA artifacts for cross-agent attestation:

```yaml
artifact:
  type: memory
  gam:
    id: mem_1708344000000_a1b2
    commit: 8a7f3b2c
  provenance:
    actor: ada@substr8labs.com
    timestamp: 2026-02-19T08:00:00Z
```

## Commands

| Command | Description |
|---------|-------------|
| `gam init [path]` | Initialize GAM repository |
| `gam remember <content>` | Store a new memory |
| `gam recall <query>` | Search memories |
| `gam verify <id>` | Verify provenance |
| `gam forget <id>` | Delete a memory |
| `gam status` | Repository status |
| `gam show <id>` | Display a memory |

## License

MIT - Substr8 Labs