timmy-config/wizards/allegro-primus/knowledge/README.md

# AP Knowledge Base

A hierarchical memory storage system for Allegro-Primus based on the memdir pattern from Claude Code.

## Overview

The AP Knowledge Base provides persistent, file-based memory storage with:

- **Hierarchical organization** - Memories organized by type (fact, procedure, observation, lesson)
- **Memory aging** - Automatic freshness scoring based on age
- **Relevance scoring** - Search and rank memories by relevance
- **Memory consolidation** - Merge similar memories automatically
- **Knowledge graph** - Track relationships between memories
- **Father sync** - Sync knowledge with father's teachings

## Memory Types

| Type | Description | Example |
|------|-------------|---------|
| `fact` | Facts about users, systems, or context | "User prefers Python over JavaScript" |
| `procedure` | How-to guidance and workflows | "Deployment checklist for production" |
| `observation` | Point-in-time observations | "Build failed due to missing dependency" |
| `lesson` | Learned insights from experience | "Mocking databases caused test drift" |

## Directory Structure

```
~/.ap/knowledge/
├── MEMORY.md              # Auto-generated index
├── facts/                 # Fact memories
├── procedures/            # Procedure memories
├── observations/          # Observation memories
├── lessons/               # Lesson memories
├── archive/               # Archived memories
├── relationships.json     # Knowledge graph edges
├── lineage.json          # Memory lineage tracking
└── sync/                 # Father sync directory
    ├── inbox/            # Imports from father
    ├── outbox/           # Exports to father
    └── processed/        # Processed sync files
```

## Memory File Format

Memories are stored as Markdown with YAML frontmatter:

```markdown
---
id: abc123
name: Python coding standards
description: Best practices for Python development
type: procedure
scope: team
created: 2024-01-15T10:30:00
modified: 2024-01-15T10:30:00
tags: python, coding, standards
source: father
confidence: 0.95
---

Always use type hints for function signatures.
Write docstrings for all public functions.
Follow PEP 8 style guidelines.
```

## CLI Usage

### Add a Memory

```bash
# Interactive
ap-kb add-memory --name "Deployment process" --type procedure --tags deploy

# With content
ap-kb add-memory --name "API endpoint" --type fact --content "Base URL is https://api.example.com"
```

### Search Memories

```bash
# Basic search
ap-kb search python

# Filter by type
ap-kb search deploy --type procedure

# Filter by tags
ap-kb search --tags python best-practices
```

### List Memories

```bash
# All memories
ap-kb list

# By type
ap-kb list --type fact lesson

# Sorted by access count
ap-kb list --sort access
```

### Consolidate Similar Memories

```bash
# Preview what would be merged
ap-kb consolidate --dry-run

# Actually consolidate
ap-kb consolidate
```

### Sync with Father

```bash
# Show sync status
ap-kb sync --status

# Export for father review
ap-kb sync --export --scope team

# Import father's teachings
ap-kb sync --import

# Create complete package
ap-kb sync --package --notes "Please review deployment procedures"
```

### Knowledge Graph

```bash
# Create relationship
ap-kb relate memory1_id memory2_id --type related --description "Similar topic"

# Visualize
ap-kb visualize
```

## Python API

```python
from pathlib import Path
from knowledge import MemoryDirectory, MemoryEntry, MemoryType, MemoryQuery

# Initialize
memdir = MemoryDirectory(Path("~/.ap/knowledge"))

# Create memory
entry = MemoryEntry(
    name="User preference",
    description="User prefers dark mode",
    type=MemoryType.FACT,
    content="Always use dark mode for UI components",
    tags=["ui", "preferences"]
)

# Save
memdir.save(entry)

# Search
results = memdir.search(MemoryQuery(
    text="dark mode",
    types=[MemoryType.FACT],
    limit=5
))

for entry, score in results:
    print(f"{entry.name}: {score}")

# Find similar
similar = memdir.find_similar(entry, threshold=0.8)

# Consolidate
merged = memdir.consolidate()
```

## Knowledge Graph

Track relationships between memories:

```python
from knowledge import KnowledgeGraph, RelationshipType

graph = KnowledgeGraph(Path("~/.ap/knowledge"))

# Add relationship
graph.add_relationship(
    source_id="mem1",
    target_id="mem2",
    rel_type=RelationshipType.DERIVED_FROM,
    description="Based on original research"
)

# Get lineage
lineage = graph.get_lineage("mem2")
print(lineage["ancestors"])  # ['mem1']

# Find related memories
related = graph.find_related("mem1", max_depth=2)
```

## Father Sync

Synchronize knowledge with father's teachings:

```python
from knowledge import FatherSync

sync = FatherSync(memdir)

# Export for father
sync.export_for_father(scope=MemoryScope.TEAM)

# Import teachings
imported, skipped, conflicts = sync.import_from_father()

# Resolve conflicts
for conflict in conflicts:
    sync.resolve_conflict(conflict, resolution='merge')
```

## Configuration

Environment variables:

- `AP_KNOWLEDGE_DIR` - Override default knowledge directory

## Installation

```bash
# Make CLI executable
chmod +x /root/wizards/allegro-primus/knowledge/cli.py

# Optional: Add to PATH
ln -s /root/wizards/allegro-primus/knowledge/cli.py /usr/local/bin/ap-kb
```

## Dependencies

Core:
- Python 3.8+
- networkx (for knowledge graph)

Optional:
- matplotlib (for visualization)

## License

MIT - Allegro-Primus Project