Update README.md
This commit is contained in:
neo committed
1 parent
fb1d25cb56
commit
cf598ae6bb
1 file changed
+113
-1
@@ -1,2 +1,114 @@
|
||||
# cyborg-architecture
|
||||
# Cyborg Architecture v1.0
|
||||
|
||||
**Status:** Architecture Design — Phase 1 (Planning)
|
||||
**Type:** Local Knowledge Infrastructure
|
||||
**Hardware:** 128 GB RAM Server (no GPU), 90 GB DDR5 Desktop
|
||||
|
||||
## Vision
|
||||
|
||||
Build a deterministic, proactive knowledge layer that transforms a reactive LLM agent into a **cyborg-like system** with:
|
||||
|
||||
- **Proactive initiative** — predicts next steps before being asked
|
||||
- **Accurate foresight** — risk analysis based on graph dependencies and vector memory
|
||||
- **Deterministic reliability** — no emotional noise, pure signal + structured knowledge
|
||||
- **Self-improving memory** — learns from feedback, updates facts, prunes noise
|
||||
|
||||
## Core Problem
|
||||
|
||||
Standard LLM architecture is a "glass sphere" — it only sees what's in the current context. When a session ends, it "forgets" unless manually saved to memory. The system is reactive, not proactive.
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
### Layer 1: Memgraph (Graph Database)
|
||||
- **Role:** Semantic relationships and dependencies
|
||||
- **Why Memgraph over Neo4j:** Full Cypher compatibility, native C++ (no JVM overhead), ~200-400 MB RAM vs 2-4 GB, faster on single-core
|
||||
- **Use cases:**
|
||||
- File-to-file dependency graphs
|
||||
- "What breaks if I change X?" queries
|
||||
- Project knowledge graph (functions → files → modules → projects)
|
||||
- Risk path analysis (find all code paths affected by a change)
|
||||
|
||||
### Layer 2: Qdrant (Vector Database)
|
||||
- **Role:** Semantic search and pattern matching
|
||||
- **Why Qdrant over Milvus:** Rust-based (no GC pauses), single binary, lightweight (~150-300 MB RAM), powerful filters, full RAM access for fast lookups
|
||||
- **Use cases:**
|
||||
- "How did I solve this before?" — semantic code search
|
||||
- Personal coding patterns memory
|
||||
- Feedback and correction history
|
||||
- Cross-project pattern extraction
|
||||
|
||||
### Layer 3: Mem0 (Agent Memory Manager)
|
||||
- **Role:** The "synapses" between agent and databases
|
||||
- **Functions:**
|
||||
- Noise filtering — stores only significant facts
|
||||
- Memory updates — overwrites old facts when corrected
|
||||
- Confidence scoring — rates memory reliability
|
||||
- Automatic deduplication
|
||||
- **Integration:** Native providers for Qdrant + Neo4j-compatible (Memgraph)
|
||||
|
||||
### Layer 4: Ollama + Qwen2.5-7B (Local Router)
|
||||
- **Role:** Fast dispatch and classification (not full reasoning)
|
||||
- **Why 7B not 30B+:**
|
||||
- 30B Q4 on CPU → ~5-8 tokens/sec (DDR5 memory bandwidth bottleneck)
|
||||
- 7B Q4 on CPU → ~15-30 tokens/sec (acceptable for routing)
|
||||
- 7B in ~5-6 GB RAM vs ~18 GB for 30B
|
||||
- **Use cases:**
|
||||
- Intent classification
|
||||
- Entity extraction from messages
|
||||
- Routing to correct database/knowledge path
|
||||
- Plan validation and decomposition
|
||||
- **Optimization:** `mlock`, `--threads` = physical cores, `--ctx-size 4096`, Q4_K_M
|
||||
|
||||
### Layer 5: Async Event Bus (Python + asyncio)
|
||||
- **Role:** Decouple agent from inference latency
|
||||
- **Pattern:** Event-driven workers, not blocking LLM calls
|
||||
- **Flow:**
|
||||
1. Agent action triggers event (tool call, git hook, cron tick)
|
||||
2. Event pushed to async queue
|
||||
3. Worker picks up, routes through local LLM
|
||||
4. Results written to Memgraph/Qdrant
|
||||
5. Agent reads ready results on demand
|
||||
- **Effect:** Inference latency completely hidden; system reacts instantly
|
||||
|
||||
## Deployment
|
||||
|
||||
### Container Orchestration
|
||||
- **Tool:** `podman-compose` (no root, no systemd, no CRI issues)
|
||||
- **Containers:**
|
||||
- `memgraph` — graph database
|
||||
- `qdrant` — vector database
|
||||
- `ollama` — local LLM router
|
||||
- `worker` — Python async workers (Mem0, ingestion, routing)
|
||||
- `redis-lite` (optional) — event bus for inter-service communication
|
||||
|
||||
### Memory Limits
|
||||
- `memgraph`: 1 GB
|
||||
- `qdrant`: 2 GB
|
||||
- `ollama`: 8 GB (Qwen2.5-7B Q4 + context)
|
||||
- `worker`: 4 GB
|
||||
- Total overhead: ~15 GB (leaving 113 GB for agent + system)
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **No single point of failure** — each database can function independently
|
||||
2. **Deterministic first, LLM second** — use scripts/tools before calling LLM
|
||||
3. **Async by default** — no blocking on inference
|
||||
4. **Minimal footprint** — every component chosen for low resource usage
|
||||
5. **Podman-native** — no root, no systemd dependency
|
||||
6. **Scalable** — can add more databases or models without architectural changes
|
||||
|
||||
## Future Phases
|
||||
|
||||
- **Phase 1 (Current):** Infrastructure setup, data ingestion pipeline
|
||||
- **Phase 2:** Dependency-aware code analysis ("what breaks when")
|
||||
- **Phase 3:** Proactive risk detection (auto-scan for anti-patterns)
|
||||
- **Phase 4:** Self-improving knowledge graph (auto-merge, dedup, confidence scoring)
|
||||
- **Phase 5:** Multi-agent coordination (specialist routers for different domains)
|
||||
|
||||
## Files
|
||||
|
||||
- `ARCHITECTURE.md` — Full architecture specification
|
||||
- `podman-compose.yml` — Container orchestration
|
||||
- `scripts/ingest.py` — Knowledge ingestion script (WIP)
|
||||
- `scripts/router.py` — Local LLM routing script (WIP)
|
||||
- `scripts/mem0-bridge.py` — Mem0 integration bridge (WIP)
|
||||
Reference in new issue
Block a user