vilona

name	vilona
description	Use when foundational core infrastructure skill providing system foundation capabilities for the agent ecosystem.
domain	core
author	oyi77
license	Apache-2.0
subdomain	core-platform
tags	["infrastructure","memory","self-improvement","vilona"]
version	1.0.0

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:

Opportunity	Revenue Model	Investment
Brain-save-as-a-service for multi-agent teams	$20-50/mo per seat — persist cross-session context so agents never start blank	Low (wrap existing MCP tools in a subscription tier)
Custom entity management dashboard	$2K-5K build + $200/mo hosted — visual entity graph with search, drift detection, archival	Medium
Memory audit & compaction consulting	$500-2K per engagement — diagnose stale entity structures, optimize config, recover lost context	Low
Offline-first memory sync for air-gapped deployments	$5K-10K license — vilona entity protocol running on disconnected networks with periodic sync	High
Agent onboarding package — entity mapping + brain rules + session hooks	$1K-3K flat — set up 10-20 entities, configure brain tiers, install auto-save hooks	Medium
Memory health SLA — weekly brain audits, entity compaction, drift reports	$500-1K/mo recurring — automated monitoring with human-in-the-loop review	Low

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

Rationalization	Reality
"I will add monitoring later"	Without monitoring, you cannot detect failures. Add it from day one.
"One model is enough"	Different tasks need different models. Route intelligently.
"Premature optimization"	Infrastructure decisions are hard to change later. Design for scale early.

# 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=)

    entity = {
        : sanitized,
        : entity_type,
        : datetime.now().strftime(),
        : [],
        : facts  [],
        : []
    }

    filepath = ENTITIES_DIR / 
     (filepath, )  f:
        f.write()
        yaml.dump(entity, f, default_flow_style=, sort_keys=)
        f.write()

    
    _update_index(sanitized, entity_type)
     filepath


 ():
    
    filename = sanitize_name(entity_name)
    filepath = ENTITIES_DIR / 

      filepath.exists():
         FileNotFoundError()

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

    data[].insert(, fact)            
    data[] = data[][:max_facts]  
    data[] = datetime.now().strftime()

     (filepath, )  f:
        f.write()
        yaml.dump(data, f, default_flow_style=, sort_keys=)
        f.write()

    _update_index(filename, data[])
     data[][]  


 ():
    
    index = {: {}, : datetime.now().isoformat()}
     INDEX_PATH.exists():
        index = json.loads(INDEX_PATH.read_text())

    index[][entity_name] = {
        : ,
        : entity_type,
        : datetime.now().strftime()
    }
    index[] = datetime.now().isoformat()
    INDEX_PATH.write_text(json.dumps(index, indent=))


 () -> []:
    
      INDEX_PATH.exists():
         []
    index = json.loads(INDEX_PATH.read_text())
    items = index.get(, {})
     entity_type:
         [{: k, **v}  k, v  items.items()  v.get() == entity_type]
     [{: k, **v}  k, v  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

 () -> []:
    
    
    
     []  


 () -> :
    
    
    
    




 () -> :
    
    session_id = 
    sessions_dir = MEMORY_DIR / 
    sessions_dir.mkdir(parents=, exist_ok=)

    
    entities_loaded = []
     INDEX_PATH.exists():
        index = json.loads(INDEX_PATH.read_text())
        sorted_entities = (
            index[].items(),
            key= e: e[].get(, ),
            reverse=
        )[:]
        entities_loaded = [name  name, _  sorted_entities]

     {: session_id, : entities_loaded}


 ():
    
    session_data = {
        : datetime.now().strftime(),
        : os.urandom().(),
        : summary  ,
        : decisions  []
    }

    trace_path = MEMORY_DIR /  / 
     (trace_path, )  f:
        f.write()
        yaml.dump(session_data, default_flow_style=, sort_keys=)
        f.write()

    
    save_result = brain_remember(
        content=summary  ,
        category=,
        importance=
    )

     {: (trace_path), : save_result}


 () -> []:
    
    cutoff = datetime.now() - timedelta(days=days)
    recent = []
    sessions_dir = MEMORY_DIR / 

      sessions_dir.exists():
         []

     f  (sessions_dir.glob(), reverse=)[:]:
        mtime = datetime.fromtimestamp(f.stat().st_mtime)
         mtime < cutoff:
            
        frontmatter = f.read_text().split()[]
        data = yaml.safe_load(frontmatter)
        recent.append({
            : data.get(),
            : data.get(),
            : data.get(, ),
            : data.get(, []),
            : data.get(, )[:]
        })

     recent

Common Issues & Troubleshooting

Problem	Solution
Brain save returns timeout after compaction	Brain compaction runs async and may block subsequent writes. Retry with 5s exponential backoff. Check xd://mcp__ai_hub_vilona_health for system load before retrying.
Entity name collision after sanitization	Two different names produce the same filename (e.g., "My Project" and "my-project" both become my-project.md). Always use unique canonical names. Prefix with type: project-, person-, tool-. Check index.json for duplicates before creation.
Session context is stale on resume	Session trace file was created but never finalized. Run session_end() manually or 1ai memory session-end --force to flush. The auto-brain-save hook may have missed firing if the commit hook was overridden or skipped.
Memory recall returns no results	A brain layer (gbrain) may be unreachable. Verify with xd://mcp__ai_hub_vilona_health. Fall back to local entity files at ~/.1ai/memory/entities/ — these work offline and don't depend on gbrain. Use FTS5 grep search on those files as last resort.
Entity frontmatter YAML parse error	An unescaped colon or special character in a fact string breaks yaml.safe_load(). Diagnose with: python -c "import yaml; yaml.safe_load(open('path'))". Wrap parse in try/except and fall back to raw markdown body. Repair by editing the YAML frontmatter directly.
Compaction deletes useful sessions before TTL	Default session TTL is 30 days (configurable in config.yaml). Extract key facts into the entity file before compaction runs — entities persist indefinitely. Set session.ttl_days: 90 in config.yaml for important projects.
Multi-agent entity write conflicts	Two agents writing the same entity file concurrently can overwrite each other's facts. Use the write-then-verify pattern: write, re-read, confirm your fact appears. Run 1ai memory status to rebuild the index and resolve inconsistencies at session boundaries.

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