# Hermes Memory Next Level — Integrations-Plan

**Ziel:** Schrittweise Integration in Hermes Agent ohne Breaking Changes.

---

## 1. Memory Tool Erweiterung (tools/memory_tool.py)

### Neue Actions

```python
# Bestehende Actions: add, replace, remove, read
# Neue Actions für Tier 2/3/Graph:

"fact_store"     -> api.fact_store(content, category, confidence, source)
"fact_query"     -> api.fact_query(query, category, limit)
"entity_ensure"  -> api.entity_ensure(name, entity_type, aliases)
"entity_link"    -> api.entity_link(from_name, to_name, relation)
"semantic_search"-> api.semantic_search(query, limit)
"recall"         -> api.recall(query, tiers)
"stats"          -> api.stats()
```

### Implementierung

```python
# In MemoryStore oder als neues Modul
from hermes_memory import MemoryAPI

class NextLevelMemoryStore:
    def __init__(self):
        self.api = MemoryAPI()
    
    def handle_action(self, action: str, **kwargs) -> dict:
        handler = getattr(self, f"_handle_{action}", None)
        if handler:
            return handler(**kwargs)
        return {"success": False, "error": f"Unknown action: {action}"}
```

---

## 2. Session Search Tool (tools/session_search_tool.py)

### Automatische Indexierung

```python
# Nach Discovery/Scroll: Indexiere Ergebnisse in Tier 3

def _index_results(results: list, session_id: str):
    api = MemoryAPI()
    for r in results:
        api.semantic_index(
            text=r.get("content", "")[:1000],
            source_type="session",
            session_id=session_id,
            message_id=r.get("id")
        )
```

---

## 3. Cronjob Scheduler (cron/scheduler.py)

### Neue Jobs registrieren

```python
# In scheduler.py oder jobs.py:
from hermes_memory.cron import run_consolidate, run_embed_queue, run_graph_refresh, run_prune

MEMORY_CRON_JOBS = {
    "memory.consolidate": {
        "schedule": "0 3 * * *",
        "func": run_consolidate,
    },
    "memory.embed_queue": {
        "schedule": "*/5 * * * *",
        "func": run_embed_queue,
    },
    "memory.graph_refresh": {
        "schedule": "0 4 * * 0",
        "func": run_graph_refresh,
    },
    "memory.prune": {
        "schedule": "0 2 1 * *",
        "func": run_prune,
    },
}
```

---

## 4. Skills System

### Skill-Manifest Erweiterung

```json
{
  "name": "project_tracker",
  "memory_tiers": ["tier2", "tier3"],
  "memory_queries": [
    "aktuelle Projekte",
    "technische Entscheidungen"
  ]
}
```

### Skill-Context Injection

```python
# In skill_manager_tool.py:
def _inject_memory_context(skill_id: str, query: str) -> str:
    api = MemoryAPI()
    context = api.recall(query, tiers=["tier1", "tier2"], limit_per_tier=3)
    return format_memory_context(context)
```

---

## 5. System Prompt Integration

```python
# In agent_init.py / prompt_builder.py:

def build_memory_context(api: MemoryAPI) -> str:
    parts = []
    
    # Tier 1: Curated (frozen snapshot)
    parts.append(api.curated_get("memory"))
    parts.append(api.curated_get("user"))
    
    # Tier 2: Relevante Fakten
    facts = api.fact_query(category="user", limit=5, min_confidence=0.8)
    parts.append("## Bekannte Fakten\n" + format_facts(facts))
    
    # Graph: Zentrale Entitäten
    central = api.graph_central_entities(limit=5)
    parts.append("## Wichtige Entitäten\n" + format_entities(central))
    
    return "\n\n".join(parts)
```

---

## 6. Migrationsschritte

### Phase 1: Tier 2 (SQLite)
- [ ] `hermes_memory/` in Hermes-Codebase kopieren
- [ ] `memory_tool.py` um Tier-2-Actions erweitern
- [ ] Schema-Initialisierung bei Agent-Start
- [ ] Test: Fakten speichern & abfragen

### Phase 2: Tier 3 (Chroma)
- [ ] `chromadb` als optional dependency
- [ ] Embedding-Queue implementieren
- [ ] `semantic_search` Action hinzufügen
- [ ] Session-Search-Integration

### Phase 3: Graph (NetworkX)
- [ ] Entity-Extraktion aus Sessions
- [ ] Graph-Builder implementieren
- [ ] Traversal-Tools hinzufügen

### Phase 4: Unified API
- [ ] Cross-Tier `recall()` implementieren
- [ ] Skill-Memory-Adapter
- [ ] Performance-Optimierung

---

*Integrations-Plan v1.0*