Vilona

Vilona Skill

When to Use

Trigger phrases: Trigger phrases:

• "vilona"
• "Help me with vilona"

Use cases:

• When the task matches this skill's domain expertise

When NOT to use:

• For tasks outside this skill's scope

When NOT to Use

• When the task can be solved with existing standard libraries
• When the infrastructure is already in place and working
• When the added complexity does not provide measurable benefit

Overview

Vilona is a foundational core infrastructure skill that provides system foundation capabilities for the agent ecosystem.

Architecture

• Input layer — Receives and validates incoming requests
• Processing layer — Core logic for system foundation
• Output layer — Formats and delivers results
• State management — Maintains context across invocations

Configuration

• Set up required environment variables and paths
• Configure logging level and output format
• Define resource limits (memory, time, API calls)
• Enable/disable features via configuration flags

Integration

• Exposes standard interfaces for other skills to consume
• Supports event-driven and request-response patterns
• Compatible with the 1ai-skills hook system
• Logs metrics for the skill performance monitor

Money-Making Overview

Vilona's brain and entity memory system is the persistence layer that turns short-lived agent sessions into an accumulating knowledge asset. This has direct monetization value:

The core insight: every lost context costs $50-200 in re-discovery time. With 5+ agent sessions per day, a well-maintained vilona memory system saves $250-1,000/day versus starting blind each session.

Anti-Rationalization Table

# Example: Model routing
ROUTES = {
    "code": ["claude-sonnet-4-20250514", "gpt-4o"],
    "vision": ["gemini-2.5-pro", "gpt-4o"],
    "fast": ["gemini-2.5-flash", "gpt-4o-mini"],
}

def route_request(task: str, prompt: str):
    models = ROUTES.get(task, ROUTES["fast"])
    for model in models:
        try:
            return call_model(model, prompt)
        except Exception:
            continue
    raise RuntimeError("All models failed")

Code Examples: Entity Management

Entities are the atomic unit of vilona memory. Each entity represents a project, person, concept, or tool with structured YAML frontmatter following the GAP-002 protocol defined in _rules/MEMORY.md.

import yaml
import json
import os
from pathlib import Path
from datetime import datetime

MEMORY_DIR = Path.home() / ".1ai" / "memory"
ENTITIES_DIR = MEMORY_DIR / "entities"
INDEX_PATH = MEMORY_DIR / "index.json"


def sanitize_name(name: str) -> str:
    """Sanitize an entity name per GAP-002 rules:
    1. Lowercase
    2. Replace non-alphanumeric (except . and -) with -
    3. Collapse consecutive hyphens
    4. Strip leading/trailing hyphens
    """
    name = name.lower()
    name = "".join(c if c.isalnum() or c in "-." else "-" for c in name)
    while "--" in name:
        name = name.replace("--", "-")
    return name.strip("-")


def create_entity(name: str, entity_type: str, facts: list[str] = None):
    """Create a new entity file following GAP-002 format.

    Args:
        name: Canonical entity name (auto-sanitized for filename)
        entity_type: One of: project, person, concept, tool, domain
        facts: Initial list of known-true statements (newest-first order)

    Returns:
        Path to the created entity file
    """
    sanitized = sanitize_name(name)
    ENTITIES_DIR.mkdir(parents=True, exist_ok=True)

    entity = {
        "name": sanitized,
        "type": entity_type,
        "last_seen": datetime.now().strftime("%Y-%m-%d"),
        "aliases": [],
        "facts": facts or [],
        "decisions": []
    }

    filepath = ENTITIES_DIR / f"{sanitized}.md"
    with open(filepath, "w") as f:
        f.write("---\n")
        yaml.dump(entity, f, default_flow_style=False, sort_keys=False)
        f.write("---\n")

    # Update index.json for fast lookups
    _update_index(sanitized, entity_type)
    return filepath


def add_entity_fact(entity_name: str, fact: str, max_facts: int = 50):
    """Append a fact to an existing entity in reverse-chronological order.

    Automatically enforces GAP-002 limit of 50 facts per entity.
    Args:
        entity_name: Canonical name (or sanitized filename)
        fact: Complete statement to record
    """
    filename = sanitize_name(entity_name)
    filepath = ENTITIES_DIR / f"{filename}.md"

    if not filepath.exists():
        raise FileNotFoundError(f"Entity '{entity_name}' not found at {filepath}")

    raw = filepath.read_text()
    parts = raw.split("---")
    data = yaml.safe_load(parts[1])

    data["facts"].insert(0, fact)            # Newest first
    data["facts"] = data["facts"][:max_facts]  # Enforce cap
    data["last_seen"] = datetime.now().strftime("%Y-%m-%d")

    with open(filepath, "w") as f:
        f.write("---\n")
        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
        f.write("---\n")

    _update_index(filename, data["type"])
    return data["facts"][0]  # Return the newly inserted fact


def _update_index(entity_name: str, entity_type: str):
    """Internal helper to keep index.json consistent with disk state."""
    index = {"entities": {}, "last_updated": datetime.now().isoformat()}
    if INDEX_PATH.exists():
        index = json.loads(INDEX_PATH.read_text())

    index["entities"][entity_name] = {
        "path": f"entities/{entity_name}.md",
        "type": entity_type,
        "last_seen": datetime.now().strftime("%Y-%m-%d")
    }
    index["last_updated"] = datetime.now().isoformat()
    INDEX_PATH.write_text(json.dumps(index, indent=2))


def list_entities(entity_type: str = None) -> list[dict]:
    """List all known entities, optionally filtered by type."""
    if not INDEX_PATH.exists():
        return []
    index = json.loads(INDEX_PATH.read_text())
    items = index.get("entities", {})
    if entity_type:
        return [{"name": k, **v} for k, v in items.items() if v.get("type") == entity_type]
    return [{"name": k, **v} for k, v in items.items()]

Code Examples: Memory Operations

Vilona manages three tiers of memory: brain (gbrain cloud persistence for cross-session recall), entity files (local structured YAML knowledge per GAP-002), and session traces (recent activity in ~/.1ai/memory/sessions/). These operations bridge all three tiers.

import json
import yaml
import os
from pathlib import Path
from datetime import datetime, timedelta

# ===== BRAIN SAVE (Write Side) =====
# Mandatory per CLAUDE.md: call after every git commit.
# MCP tool: xd://mcp__ai_hub_vilona_brain_remember

def brain_remember(content: str, category: str, importance: float = 0.8) -> dict:
    """Persist a memory entry to the Vilona brain.

    Per CLAUDE.md auto-brain-save rule, this is MANDATORY
    after every git commit. Category = project name.
    Importance >=0.8 entries survive automatic compaction.

    Args:
        content: Free-text summary of what was done/decided
        category: Project name for cross-referencing
        importance: 0.0-1.0 survival priority

    Returns:
        Confirmation dict with status and timestamp
    """
    # In production this routes through the MCP tool:
    # result = tool.mcp__ai_hub_vilona_brain_remember({
    #     "content": content,
    #     "category": category,
    #     "importance": importance
    # })
    return {
        "content": content[:80] + "..." if len(content) > 80 else content,
        "category": category,
        "importance": importance,
        "status": "stored",
        "timestamp": datetime.now().isoformat()
    }


# ===== BRAIN RECALL (Read Side) =====
# MCP tools: xd://mcp__ai_hub_vilona_brain_search / recall

def brain_search(query: str, top_k: int = 5) -> list[dict]:
    """Search ALL brain layers for knowledge matching a query.

    Searches gbrain, mempalace, FTS5 index, entity files,
    and KB vector DB simultaneously. Returns ranked results.
    """
    # In production:
    # return tool.mcp__ai_hub_vilona_brain_search({"query": query})
    return []  # Placeholder — call via MCP tool


def brain_recall(topic: str) -> dict:
    """Unified memory recall — combines facts, relationships,
    timeline, narrative, and pattern insights from ALL memory layers.

    This is the primary read-side tool for session continuity.
    """
    # In production:
    # return tool.mcp__ai_hub_vilona_recall({"topic": topic})
    pass


# ===== SESSION LIFE-CYCLE MANAGEMENT =====

def session_start() -> dict:
    """Initialize a new session: register session file, load recent entities."""
    session_id = f"{datetime.now().strftime('%Y%m%d')}-{os.urandom(4).hex()}"
    sessions_dir = MEMORY_DIR / "sessions"
    sessions_dir.mkdir(parents=True, exist_ok=True)

    # Load recent context: top-10 entities by recency
    entities_loaded = []
    if INDEX_PATH.exists():
        index = json.loads(INDEX_PATH.read_text())
        sorted_entities = sorted(
            index["entities"].items(),
            key=lambda e: e[1].get("last_seen", ""),
            reverse=True
        )[:10]
        entities_loaded = [name for name, _ in sorted_entities]

    return {"session_id": session_id, "entities_loaded": entities_loaded}


def session_end(summary: str = None, decisions: list[str] = None):
    """Finalize a session: write trace file, trigger brain save."""
    session_data = {
        "date": datetime.now().strftime("%Y-%m-%d"),
        "session_id": os.urandom(4).hex(),
        "outcome": summary or "Session completed",
        "decisions": decisions or []
    }

    trace_path = MEMORY_DIR / "sessions" / f"{session_data['date']}-{session_data['session_id']}.md"
    with open(trace_path, "w") as f:
        f.write("---\n")
        yaml.dump(session_data, default_flow_style=False, sort_keys=False)
        f.write("---\n")

    # Trigger persistent brain save
    save_result = brain_remember(
        content=summary or "Session completed",
        category="session",
        importance=0.7
    )

    return {"trace_file": str(trace_path), "brain_save": save_result}


def recall_recent_sessions(days: int = 7) -> list[dict]:
    """Load recent session traces for context continuity."""
    cutoff = datetime.now() - timedelta(days=days)
    recent = []
    sessions_dir = MEMORY_DIR / "sessions"

    if not sessions_dir.exists():
        return []

    for f in sorted(sessions_dir.glob("*.md"), reverse=True)[:20]:
        mtime = datetime.fromtimestamp(f.stat().st_mtime)
        if mtime < cutoff:
            break
        frontmatter = f.read_text().split("---")[1]
        data = yaml.safe_load(frontmatter)
        recent.append({
            "date": data.get("date"),
            "id": data.get("session_id"),
            "tasks": data.get("tasks_completed", 0),
            "entities": data.get("entities", []),
            "outcome": data.get("outcome", "")[:100]
        })

    return recent

Common Issues & Troubleshooting

Process

1. Initialize session context — Run vilona_brain_recall or session-warmup flow to load recent entity facts, open decisions, and session history. Verify brain health via xd://mcp__ai_hub_vilona_health before proceeding.
2. Load entities — Read relevant entity files from ~/.1ai/memory/entities/. Cross-reference via ~/.1ai/memory/index.json for complete entity graph. Query gbrain for project-specific context. Apply entity:// URI references if present in task definitions (GAP-017).
3. Execute infrastructure workflow — Run the core vilona operation: deploy memory hooks, trigger brain save, manage MCP tool registrations, or update entity files per GAP-002 protocol. Use auto-brain-save after every git commit.
4. Validate memory persistence — Confirm brain save succeeded by calling vilona_brain_search or reading the audit log (xd://mcp__ai_hub_vilona_audit). Verify entity files on disk match expectations. Check session trace is recorded.
5. Close session — Finalize session trace with session_end(). Save architectural decisions as entity facts. Run compaction if approaching entity/session limits in ~/.1ai/memory/config.yaml. Trigger brain save with importance ≥0.8 for key decisions.

Verification

• Brain health check passes (xd://mcp__ai_hub_vilona_health returns OK)
• Entity files are valid YAML and follow GAP-002 format (~/.1ai/memory/entities/)
• Session context loaded from brain recall (gbrain + local entities available at start)
• Brain save succeeds after work (content, category, importance recorded in audit log)
• Entity index (~/.1ai/memory/index.json) is consistent with on-disk entity files
• No stale entity files — check last_seen dates, archive if >90 days untouched
• Multi-agent shared memory verified — other agents can access the same facts via brain recall
• Rollback path documented: 1ai memory forget archives corrupted entities; git revert restores entity file history
• Session trace written with tasks_completed, entities_touched, decisions_made