251 lines
5.4 KiB
Markdown
251 lines
5.4 KiB
Markdown
# 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
|