Related Pages

Related topics: Three-Layer Architecture, Quick Start Guide

Introduction to OMPA

OMPA (Obsidian-MemPalace-Agnostic) is a lightweight, framework-agnostic memory management system designed for AI agents. It provides persistent storage, semantic search, knowledge graph tracking, and a palace metaphor for organizing notes and memories across sessions.

Overview

OMPA serves as a second brain for AI agents, enabling them to:

• Persist and retrieve information across sessions
• Classify and automatically route messages to appropriate storage locations
• Search vault contents using semantic similarity
• Track temporal knowledge graphs with validity windows
• Navigate a hierarchical palace structure (wings, rooms, drawers, halls, tunnels)

The project was renamed from "AgnosticObsidian" to OMPA in version 0.2.0, with backward compatibility preserved via an alias. Sources: CHANGELOG.md:1-10

Key Features

Architecture

OMPA follows a layered architecture with distinct responsibilities:

graph TD
    subgraph "OMPA Architecture"
        CLI[CLI<br>14 commands]
        MCP[MCP Server<br>15 tools]
        Core[Core Module<br>Ompa class]
        Vault[Vault<br>CRUD operations]
        Palace[Palace<br>Metadata layers]
        KG[Knowledge Graph<br>SQLite triples]
        Semantic[Semantic Index<br>Embeddings]
        Classifier[Classifier<br>15 message types]
        Hooks[Hook Manager<br>Lifecycle hooks]
    end
    
    CLI --> Core
    MCP --> Core
    Core --> Vault
    Core --> Palace
    Core --> KG
    Core --> Semantic
    Core --> Classifier
    Core --> Hooks

Core Components

#### 1. Vault (ompa/vault.py)

The Vault layer handles file-based storage for notes. It provides:

• Brain/work/org/perf folder organization
• Note CRUD operations
• Orphan detection
• Path traversal protection
• UTF-8 encoding enforcement

Sources: README.md:47-56

#### 2. Palace (ompa/palace.py)

The Palace metadata layer provides hierarchical navigation:

• Wings: Top-level categories
• Rooms: Secondary divisions within wings
• Drawers: Tertiary storage units
• Halls: Cross-room connections
• Tunnels: Cross-wing shortcuts

#### 3. Knowledge Graph (ompa/knowledge_graph.py)

Temporal knowledge graph backed by SQLite:

• Triple storage: (subject, predicate, object)
• Validity windows: valid_from and valid_to timestamps
• Timeline queries for entity history
• Auto-population from vault wikilinks and frontmatter

#### 4. Classifier (ompa/classifier.py)

Message classification engine supporting 15 message types:

Sources: ompa/classifier.py:1-50

#### 5. Semantic Search (ompa/semantic.py)

Local semantic search using sentence-transformers:

• Lazy model loading (downloaded on first access)
• Incremental indexing (tracks file modification times)
• Cosine similarity scoring
• Optional feature via pip install ompa[all]

#### 6. Hooks (ompa/hooks.py)

Lifecycle hooks for extending OMPA behavior:

graph LR
    SS[session_start] --> CB[Hook execution]
    HM[handle_message] --> CB
    PT[post_tool] --> CB
    PC[pre_compact] --> CB
    ST[stop] --> CB
    
    CB --> HR[HookResult]

Sources: CONTRIBUTING.md:43-54

#### 7. MCP Server (ompa/mcp_server.py)

Model Context Protocol server exposing 15 tools:

graph TD
    MCP[JSON-RPC<br>stdin/stdout] --> Tools
    Tools --> ao_session_start
    Tools --> ao_classify
    Tools --> ao_search
    Tools --> ao_kg_query
    Tools --> ao_kg_add
    Tools --> ao_kg_stats
    Tools --> ao_palace_wings
    Tools --> ao_palace_rooms
    Tools --> ao_palace_tunnel
    Tools --> ao_validate
    Tools --> ao_wrap_up
    Tools --> ao_status
    Tools --> ao_orphans
    Tools --> ao_kg_populate
    Tools --> ao_init

Sources: CLAUDE.md:1-15

Installation

Package Options

# Core only (vault + palace + KG + CLI + MCP)
pip install ompa

# With local semantic search
pip install ompa[all]

# Development dependencies
pip install ompa[dev]

Requirements: Python 3.10+

Sources: README.md:36-44

Quick Start

# Initialize vault
ao init

# Check vault health
ao status

# Start a session
ao session-start

# Classify a message
ao classify "We decided to go with Postgres"

# Search vault
ao search "authentication decisions"

# Query knowledge graph
ao kg-query Kai

# End session
ao wrap-up

Dual-Vault Architecture

OMPA supports separating team/organization content from personal notes:

from ompa import Ompa, DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)
ao = Ompa(config=config)

Isolation Modes

Sources: README.md:57-71

Python API

Core Class

from ompa import Ompa

ao = Ompa(vault_path="./workspace")

# Lifecycle
context = ao.session_start()              # Returns ~2K token context string
hint = ao.handle_message("We won the enterprise deal!")
ao.post_tool("write", {"file_path": "work/active/auth.md"})
ao.wrap_up()                              # alias for stop()
ao.standup()                              # alias for session_start()

# Search
results = ao.search("authentication decisions", wing="Orion")

# Classification
classification = ao.classify(message)
routing_hint = ao.get_routing_hint(message)

# Knowledge graph
ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
triples = ao.kg.query_entity("Kai")
timeline = ao.kg.timeline("Orion")

Sources: STABILITY.md:12-45

Data Classes

HookResult(hook_name, success, output, tokens_hint, error)
Classification(message_type, confidence, suggested_action, routing_hints)
SearchResult(path, content_excerpt, score, match_type)
Triple(subject, predicate, object, valid_from, valid_to, confidence, source_file)

MCP Desktop Integration

OMPA integrates with AI coding assistants via MCP:

{
  "mcpServers": {
    "ompa": {
      "command": "python",
      "args": ["-m", "ompa.mcp_server"],
      "env": {
        "OMPA_VAULT_PATH": "/absolute/path/to/vault"
      }
    }
  }
}

Supported IDEs

Sources: examples/mcp_desktop/README.md:1-50

Environment Variables

Project Structure

ompa/
├── core.py              # Ompa main class — lifecycle, hooks, dual-vault
├── vault.py             # Vault management (brain/work/org/perf)
├── palace.py            # Palace metadata (wings/rooms/drawers/halls/tunnels)
├── knowledge_graph.py   # Temporal KG (SQLite triples + validity windows)
├── hooks.py             # 5 lifecycle hooks + HookManager
├── classifier.py        # 15 message types with auto-routing
├── semantic.py          # Local semantic search (lazy model loading)
├── mcp_server.py        # MCP protocol server (15 tools)
├── config.py            # Dual-vault configuration
└── cli.py               # typer CLI (14 commands)

Sources: README.md:47-56

Security Features

• Path traversal protection: All vault file operations resolve and boundary-check paths against vault root Sources: CHANGELOG.md:23-26
• UTF-8 encoding enforcement: All vault file writes use UTF-8 explicitly
• Security audit: 8/10 rating with 59/59 tests passing

API Stability

OMPA follows Semantic Versioning. The stable public API includes:

• Ompa core class and all public methods
• Data classes: HookResult, Classification, SearchResult, Triple
• CLI commands and MCP tools
• Sync backends and adapters

Sources: STABILITY.md:1-50

Framework Compatibility

CLI Reference

Sources: README.md:18-37

Related Pages

Related topics: Python API Reference

Quick Start Guide

OMPA (Obsidian-MemPalace-Agnostic) is a local-first memory management system for AI agents. It provides a dual-layer architecture combining a Vault for source-of-truth note storage with a Palace for retrieval acceleration, plus a temporal Knowledge Graph for entity tracking. This guide walks you through installation, vault initialization, CLI usage, Python API integration, and MCP server setup.

Related Pages

Related topics: Introduction to OMPA

Feature Comparison

OMPA (Obsidian-MemPalace-Agnostic) is a memory management system for AI agents that provides persistent context injection, semantic search, temporal knowledge graphs, and palace-style memory navigation. This page compares the various features, components, and integration options available in the project.

Architecture Overview

OMPA follows a dual-layer architecture where the Vault serves as the source of truth for notes, and the Palace provides retrieval acceleration through metadata organization.

graph TD
    A[Agent Session] --> B[Ompa Core]
    B --> C[Vault Layer]
    B --> D[Palace Layer]
    B --> E[Knowledge Graph]
    B --> F[Semantic Index]
    C --> G[brain/ work/ org/ perf/]
    D --> H[Wings → Rooms → Drawers]
    E --> I[SQLite Triples]
    F --> J[Local Embeddings]

Sources: CLAUDE.md

Core Components

Package Structure

The codebase is organized into modular components, each handling a specific responsibility.

Sources: README.md:70-83

Installation Options

OMPA offers tiered installation to accommodate different use cases.

Sources: README.md:52-60

Environment Variables

Sources: examples/mcp_desktop/README.md

Dual-Vault Architecture

OMPA supports isolating team/organization content from personal or private notes through a dual-vault architecture.

Isolation Modes

Sources: CHANGELOG.md:2026-04-10

Configuration

from ompa import Ompa, DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)
ao = Ompa(config=config)

Sources: README.md:28-36

Dual-Vault MCP Tools

Sources: CHANGELOG.md:2026-04-10

Message Classification

The classifier categorizes incoming agent messages into 15 types with auto-routing.

Message Types

Sources: ompa/classifier.py

CLI Commands

The ao CLI provides 14 commands for vault operations.

Sources: README.md:42-57

MCP Server Tools

The MCP server exposes 15 tools via JSON-RPC protocol over stdin/stdout.

Tool List

Sources: ompa/mcp_server.py

MCP Protocol Version

Framework Compatibility

OMPA is designed to be framework-agnostic with no agent SDK dependencies.

Sources: README.md:88-94

MCP Desktop Integration

Sources: examples/mcp_desktop/README.md

Lifecycle Hooks

OMPA provides 5 lifecycle hooks for extensibility.

Sources: ompa/hooks.py

Hook Data Structures

HookResult(hook_name, success, output, tokens_hint, error)
HookContext(vault_path, session_id, timestamp, agent_name, memory)

Sources: STABILITY.md

Knowledge Graph

Data Model

graph LR
    A[Subject] -->|Predicate| B[Object]
    B -->|valid_from| C[Start Date]
    B -->|valid_to| D[End Date]
    B -->|confidence| E[Score]
    B -->|source| F[File]

API Methods

Sources: ompa/core.py

Semantic Search

Features

Sources: CHANGELOG.md:2026-04-08

Stable APIs

The following APIs are guaranteed stable within major versions.

Data Classes

HookResult(hook_name, success, output, tokens_hint, error)
Classification(message_type, confidence, suggested_action, routing_hints)
SearchResult(path, content_excerpt, score, match_type)
Triple(subject, predicate, object, valid_from, valid_to, confidence, source_file)
SyncResult(success, backend, direction, files_changed, message, error, details)

Sources: STABILITY.md

Enums

MessageType      # 15 values: DECISION, INCIDENT, WIN, ...
IsolationMode    # AUTO, STRICT, MANUAL
VaultTarget      # SHARED, PERSONAL

Security Features

Sources: CHANGELOG.md:2026-04-11

Python Version Requirements

Sources: README.md:65

Related Pages

Related topics: Vault System, Palace System, Knowledge Graph

Three-Layer Architecture

OMPA implements a three-layer architecture designed for AI agent memory management. Each layer serves a distinct purpose while maintaining loose coupling through well-defined interfaces. This architecture separates storage (Vault), retrieval acceleration (Palace), and temporal relationship tracking (Knowledge Graph).

Overview

The three layers work in concert to provide comprehensive memory capabilities for AI agents:

Sources: README.md Sources: CLAUDE.md

Architecture Diagram

graph TB
    subgraph "Layer 1: Vault"
        V[Vault Manager]
        VF[Vault Folders<br/>brain/work/org/perf]
        VP[Path Traversal Guards]
    end
    
    subgraph "Layer 2: Palace"
        P[Palace Manager]
        PW[Wings/Rooms/Drawers]
        PT[Tunnels]
    end
    
    subgraph "Layer 3: Knowledge Graph"
        KG[Knowledge Graph]
        KGS[SQLite Triples]
        KGT[Temporal Validity Windows]
    end
    
    A[Agent/AI] --> C[Ompa Core]
    C --> V
    C --> P
    C --> KG
    
    V --> VF
    P --> PW
    KG --> KGS
    
    C --> CI[Classifier]
    CI --> VF
    
    style V fill:#e1f5fe
    style P fill:#fff3e0
    style KG fill:#e8f5e9

Sources: CLAUDE.md

Layer 1: Vault

The Vault layer serves as the source of truth for all memory content. Notes are stored as Markdown files with YAML frontmatter on the file system.

Purpose and Scope

The Vault layer handles all CRUD operations for notes, enforces path security boundaries, and organizes content into logical folders based on message type classification. Every piece of information stored in OMPA ultimately lives in the Vault.

Sources: ompa/vault.py

Folder Structure

Notes are automatically routed to appropriate folders based on the MessageType classifier:

Sources: CONTRIBUTING.md

Security Features

All Vault file operations implement path traversal protection:

def _safe_resolve(vault_root: str, file_path: str) -> Path:
    # Resolves path and validates it stays within vault boundary
    # Raises SecurityError if traversal detected

Path boundaries are checked before any file read or write operation, preventing unauthorized access to files outside the vault directory. Sources: CHANGELOG.md

Dual-Vault Mode

The Vault layer supports dual-vault isolation for separating personal and shared content:

from ompa import DualVaultConfig, IsolationMode, VaultTarget

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)

Isolation Modes:

Sources: README.md

Layer 2: Palace

The Palace layer provides spatial organization and retrieval acceleration using the memory palace metaphor. It adds metadata structure on top of the Vault for fast navigation.

Purpose and Scope

The Palace layer enables agents to navigate memories using spatial concepts (wings, rooms, drawers). This mirrors the ancient method of loci technique, proven effective for memory retrieval.

"Verbatim storage: No summarization (proven 96.6% R@5 by MemPalace)"

Sources: CLAUDE.md

Palace Components

Sources: README.md

Palace Operations

# Create organizational structure
ao.palace.create_wing("Orion")
ao.palace.create_room("Orion", "decisions")
ao.palace.create_drawer("Orion", "decisions", "auth")

# Navigate with tunnels
ao.palace.create_tunnel("Orion", "Phoenix", room="shared")

Relationship to Vault

The Palace layer does not store content directly—it maintains metadata references to Vault notes. This separation allows the Palace structure to evolve independently of note content.

graph LR
    V[Vault Notes] --> P[Palace Metadata]
    P --> P1[Wings/Rooms Index]
    P --> P2[Note References]
    
    S[Search Query] --> P
    P --> R[Matched Notes]

Sources: ompa/palace.py

Layer 3: Knowledge Graph

The Knowledge Graph layer maintains temporal relationships between entities using SQLite-backed triple storage.

Purpose and Scope

The Knowledge Graph tracks facts about entities (subjects) and their relationships (predicates) to other entities (objects), with validity time windows for temporal queries.

"Temporal KG: SQLite triples with validity windows"

Sources: CLAUDE.md

Data Model

Each triple consists of:

Knowledge Graph Operations

# Add a fact with temporal validity
ao.kg.add_triple(
    subject="Kai",
    predicate="works_on",
    object="Orion",
    valid_from="2025-06-01"
)

# Query entity history
triples = ao.kg.query_entity("Kai")

# Get entity timeline
timeline = ao.kg.timeline("Orion")

Temporal Queries

The Knowledge Graph supports querying state as of a specific point in time:

# Query historical state
triples = ao.kg.query_entity("Kai", as_of="2025-07-15")

This enables agents to reason about past states of knowledge without needing to track version history manually.

Layer Interactions

Data Flow

sequenceDiagram
    participant A as Agent
    participant C as Ompa Core
    participant CL as Classifier
    participant V as Vault
    participant P as Palace
    participant KG as Knowledge Graph
    
    A->>C: handle_message("We decided...")
    C->>CL: classify(content)
    CL-->>C: Classification(WorkDecision)
    C->>V: save_note(WorkDecision)
    V-->>C: Note saved
    C->>P: update_structure(content)
    C->>KG: extract_entities(content)
    
    Note over C: Dual-vault routing<br/>applies if configured

Content Lifecycle

1. Ingestion: Message arrives at Ompa.handle_message()
2. Classification: Classifier determines message type and routing
3. Storage: Note saved to appropriate Vault (shared or personal)
4. Organization: Palace metadata updated
5. Relationship: Entities extracted and added to Knowledge Graph

graph TD
    I[Ingest Message] --> C[Classify]
    C --> R{Routing Mode}
    R -->|AUTO| A[Auto-classify]
    R -->|MANUAL| M[Manual Target]
    A --> VT{Vault Target}
    M --> VT
    VT -->|Shared| VS[Write to Shared Vault]
    VT -->|Personal| VP[Write to Personal Vault]
    
    VS --> P[Update Palace]
    VP --> P
    P --> KG[Extract Entities]
    KG --> KGA[Add to KG]

Search Integration

graph TD
    SQ[Search Query] --> C[Ompa Core]
    C -->|Semantic| SI[Semantic Index]
    C -->|Hybrid| H[Combine]
    C -->|KG| KGQ[KG Query]
    
    SI --> I[Incremental Index]
    H --> RE[Rank Results]
    KGQ --> RE
    
    RE --> R[Return Results]

The Semantic Index tracks file modification times and only re-embeds changed notes. Sources: CHANGELOG.md

Configuration

Constructor Parameters

from ompa import Ompa

ao = Ompa(
    vault_path="./workspace",           # Primary vault path
    agent_name="agent",                 # Scopes KG entries
    enable_semantic=True,              # Enable local semantic search
    embedding_backend=None,            # Custom embedding backend
    shared_vault_path=None,            # Dual-vault shared vault
    personal_vault_path=None,          # Dual-vault personal vault
    isolation_mode="strict",           # AUTO, MANUAL, or STRICT
)

Environment Variables

Sources: examples/mcp_desktop/README.md

CLI Commands by Layer

Sources: README.md

Design Principles

The three-layer architecture adheres to the following principles documented in the project:

Sources: CLAUDE.md

See Also

• API Stability — Public API guarantees
• MCP Server — MCP protocol integration
• CLI Reference — Command reference
• Contributing Guide — Development setup

Related Pages

Related topics: Three-Layer Architecture, Python API Reference

Lifecycle Hooks

Overview

Lifecycle Hooks provide a plugin-based extensibility mechanism for the OMPA memory system. They allow developers to intercept and respond to key events during an agent session, such as session initialization, message handling, tool execution, context compaction, and shutdown.

Hooks operate as an event-driven layer between the Ompa core class and the underlying vault, knowledge graph, and palace subsystems. Each hook receives a HookContext containing session metadata and returns a HookResult with execution status and token budget information.

Architecture

Component Hierarchy

graph TD
    subgraph "Ompa Core"
        A[Ompa Instance] --> B[HookManager]
    end
    
    subgraph "Hook System"
        B --> C[SessionStartHook]
        B --> D[UserMessageHook]
        B --> E[PostToolHook]
        B --> F[PreCompactHook]
        B --> G[StopHook]
        B --> H[Custom Hooks]
    end
    
    subgraph "Hook Infrastructure"
        C --> I[HookContext]
        D --> I
        E --> I
        F --> I
        G --> I
        I --> J[HookResult]
    end

Execution Flow

sequenceDiagram
    participant Agent
    participant Ompa as Ompa Core
    participant HookManager
    participant Hook as Concrete Hook
    
    Agent->>Ompa: session_start()
    Ompa->>HookManager: run_session_start(memory)
    HookManager->>HookContext: create context
    HookManager->>Hook: execute(context, **kwargs)
    Hook-->>HookManager: HookResult
    HookManager-->>Ompa: HookResult
    Ompa-->>Agent: context string (~2K tokens)
    
    Agent->>Ompa: handle_message(msg)
    Ompa->>HookManager: run_user_message(message)
    HookManager->>Hook: execute(context, message)
    Hook-->>HookManager: HookResult

Core Data Models

HookContext

Passed to every hook execution, providing runtime context.

Sources: ompa/hooks.py:10-17

HookResult

Return type from all hook executions.

Sources: ompa/hooks.py:19-23

Hook (Base Class)

class Hook(ABC):
    def __init__(self, name: str, token_budget: int = 200):
        self.name = name
        self.token_budget = token_budget
    
    @abstractmethod
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        ...

Sources: ompa/hooks.py:3-12

Default Hooks

OMPA ships with five built-in lifecycle hooks, each handling a specific phase of the agent session.

SessionStartHook

Executes at session initialization. Collects vault statistics, knowledge graph status, and palace structure to build a ~2K token context for LLM injection.

class SessionStartHook(Hook):
    def __init__(self):
        super().__init__("session_start", token_budget=200)
    
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        # Collect brain notes count
        # Fetch KG stats (triple count)
        # Gather palace wing/room structure
        # Return context string for LLM injection

StopHook

Executes during graceful shutdown. Generates a session summary, warns if the knowledge graph is empty, and persists state.

class StopHook(Hook):
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        lines = []
        lines.append(f"## Session {context.session_id} Summary")
        lines.append(f"Agent: {context.agent_name}")
        lines.append(f"Timestamp: {context.timestamp}")
        
        # KG health warning
        if kg_stats["triple_count"] == 0:
            lines.append("**WARNING:** KG is empty — run `ao kg-populate`")
        
        return HookResult(hook_name=self.name, success=True, output=output)

Sources: ompa/hooks.py:77-119

HookManager

The HookManager class orchestrates hook registration and execution.

class HookManager:
    def __init__(self, vault_path: str | Path, agent_name: str = "agent"):
        self.vault_path = Path(vault_path)
        self.agent_name = agent_name
        self.session_id = datetime.now().strftime("%Y%m%d_%H%M%S")
        self.timestamp = datetime.now()
        
        # Register default hooks
        self.hooks = {
            "session_start": SessionStartHook(),
            "user_message": UserMessageHook(),
            "post_tool": PostToolHook(),
            "pre_compact": PreCompactHook(),
            "stop": StopHook(),
        }

Sources: ompa/hooks.py:121-139

Key Methods

Integration with Ompa Core

The Ompa class exposes lifecycle methods that delegate to HookManager.

graph LR
    A[Ompa.session_start] --> B[HookManager.run_session_start]
    C[Ompa.handle_message] --> D[HookManager.run_user_message]
    E[Ompa.post_tool] --> F[HookManager.run_post_tool]
    G[Ompa.pre_compact] --> H[HookManager.run_pre_compact]
    I[Ompa.stop] --> J[HookManager.run_stop]
    
    B --> K[HookResult]
    D --> L[HookResult]
    F --> M[HookResult]
    H --> N[HookResult]
    J --> O[HookResult]

Ompa Lifecycle Methods

Sources: ompa/core.py (referenced in STABILITY.md)

Custom Hooks

Creating a Custom Hook

from ompa.hooks import Hook, HookContext, HookResult

class MetricsHook(Hook):
    def __init__(self):
        super().__init__("metrics", token_budget=50)
    
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        session_duration = datetime.now() - context.timestamp
        output = f"Session duration: {session_duration}"
        return HookResult(
            hook_name=self.name,
            success=True,
            output=output,
            tokens_hint=50
        )

Registering Custom Hooks

from ompa import Ompa

ao = Ompa("./workspace")
ao.hooks.register_hook("metrics", MetricsHook())

Replacing Default Hooks

Override default hooks by registering with the same name:

class CustomSessionStartHook(Hook):
    def __init__(self):
        super().__init__("session_start", token_budget=300)  # Higher budget
    
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        # Custom session initialization
        return HookResult(
            hook_name=self.name,
            success=True,
            output="Custom context...",
            tokens_hint=300
        )

ao.hooks.register_hook("session_start", CustomSessionStartHook())

Hook Execution Patterns

Pattern: Always Execute

Hooks execute on every invocation unless an exception is raised:

class PostToolHook(Hook):
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        tool_name = kwargs.get("tool_name")
        tool_input = kwargs.get("tool_input", {})
        
        # Always log tool execution
        log_entry = f"[{context.session_id}] {tool_name}: {tool_input}"
        append_to_log(context.vault_path / "tools.log", log_entry)
        
        return HookResult(
            hook_name=self.name,
            success=True,
            output="Tool logged",
            tokens_hint=50
        )

Pattern: Conditional Execution

Hooks can inspect context and conditionally produce output:

class UserMessageHook(Hook):
    def execute(self, context: HookContext, **kwargs) -> HookResult:
        message = kwargs.get("message", "")
        
        if is_sensitive_content(message):
            return HookResult(
                hook_name=self.name,
                success=True,
                output="",  # No output for sensitive messages
                tokens_hint=0
            )
        
        # Normal processing for non-sensitive messages
        ...

Configuration

Token Budget

Each hook declares a token_budget indicating its expected output size for context window management:

Agent Name Scoping

The agent_name parameter scopes knowledge graph entries and session identifiers:

ao = Ompa(
    vault_path="./workspace",
    agent_name="coding-agent"
)

# HookContext will receive agent_name="coding-agent"

API Stability

The hook system follows OMPA's semantic versioning policy. The following are considered stable:

• Hook base class (public interface)
• HookContext data class
• HookResult data class
• HookManager.register_hook() method

Note: Internal hook implementations (e.g., *Hook classes) may change. Use HookManager.register_hook() for custom hooks rather than subclassing internal implementations.

Sources: STABILITY.md

CLI Integration

While hooks operate at the Python API level, they are invoked through CLI commands:

Error Handling

Hooks should return HookResult with success=False on failure:

def execute(self, context: HookContext, **kwargs) -> HookResult:
    try:
        result = risky_operation()
        return HookResult(
            hook_name=self.name,
            success=True,
            output=str(result),
            tokens_hint=50
        )
    except Exception as e:
        logger.error("Hook %s failed: %s", self.name, e)
        return HookResult(
            hook_name=self.name,
            success=False,
            output="",
            error=str(e)
        )

The HookManager logs hook failures but continues execution of subsequent hooks.

Related Pages

Related topics: Three-Layer Architecture, Message Classification

Vault System

Overview

The Vault System is the core data persistence layer in OMPA (Obsidian-MemPalace-Agnostic). It provides structured storage for notes with a multi-category organization model, semantic indexing capabilities, and dual-vault isolation for separating personal and shared content.

Primary Responsibilities:

• Store and retrieve markdown notes with frontmatter metadata
• Enforce path traversal security boundaries
• Manage semantic search indices
• Support dual-vault architecture for content isolation
• Track knowledge graph relationships from note content

Sources: README.md()

Architecture

graph TD
    subgraph "Vault Layer"
        VAULT[Ompa.vault]
        BRAIN[Brain Notes]
        WORK[Work Notes]
        ORG[Org Notes]
        PERF[Performance Notes]
    end
    
    subgraph "Dual-Vault Mode"
        SHARED[Shared Vault]
        PERSONAL[Personal Vault]
        ISOLATION[IsolationMode]
    end
    
    subgraph "Index Layer"
        SEMANTIC[SemanticIndex]
        KG[KnowledgeGraph]
    end
    
    VAULT --> BRAIN
    VAULT --> WORK
    VAULT --> ORG
    VAULT --> PERF
    
    VAULT --> SEMANTIC
    VAULT --> KG
    
    VAULT --> SHARED
    VAULT --> PERSONAL
    SHARED --> ISOLATION
    PERSONAL --> ISOLATION

Note Categories

The vault organizes notes into four primary categories based on content type and access patterns.

Brain Notes

Personal knowledge, insights, and unstructured information. Brain notes form the foundation of the memory palace and are typically used for capturing ideas, learnings, and personal context.

Sources: ompa/vault.py()

Work Notes

Notes related to professional activities, projects, and work-related decisions. These notes often contain sensitive business information.

Sources: ompa/vault.py()

Org Notes

Organizational-level notes containing team decisions, processes, and shared knowledge that may be exported to the shared vault.

Sources: ompa/vault.py()

Performance Notes

Time-bounded notes tracking performance metrics, goals, and accomplishments. These notes support the temporal knowledge graph features.

Sources: ompa/vault.py()

Dual-Vault Architecture

The dual-vault architecture enables isolation between personal and shared content using DualVaultConfig and IsolationMode.

Isolation Modes

Sources: ompa/config.py()

Vault Targets

graph LR
    MSG[Message] --> CLASSIFY[Classifier]
    CLASSIFY --> TARGET{IsolationMode}
    TARGET -->|AUTO| AUTO[Auto-classify]
    TARGET -->|MANUAL| MANUAL[Manual VaultTarget]
    TARGET -->|STRICT| STRICT[Strict Mode]
    
    AUTO --> SHARED[Shared Vault]
    AUTO --> PERSONAL[Personal Vault]
    MANUAL --> SHARED
    MANUAL --> PERSONAL

Configuration

from ompa import Ompa, DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)
ao = Ompa(config=config)

Sources: README.md()

Export/Sanitization

When exporting content from personal to shared vault, OMPA automatically sanitizes sensitive information:

• sk-* (OpenAI-style API keys)
• AKIA* (AWS access key IDs)
• token:, password:, secret:, api_key:, api-key: patterns

Sources: SECURITY_AUDIT.md()

Security: Path Traversal Protection

All vault file operations resolve and boundary-check paths against the vault root before proceeding. This prevents malicious or accidental file access outside the designated vault directory.

Implementation

Flow:

graph TD
    INPUT[User Path Input] --> RESOLVE[_safe_resolve]
    RESOLVE --> CHECK{Within Vault Root?}
    CHECK -->|Yes| PROCEED[Proceed with Operation]
    CHECK -->|No| REJECT[Raise ValueError]

Sources: CHANGELOG.md(), SECURITY_AUDIT.md()

Note Storage Format

Notes are stored as Markdown files with YAML frontmatter.

Frontmatter Structure

Related Pages

Related topics: Three-Layer Architecture, Vault System

Palace System

The Palace System is a metadata layer within OMPA (Obsidian-MemPalace-Agnostic) that provides retrieval acceleration for information stored in the vault. It operates on top of the Vault layer, which serves as the source of truth for all notes, to enable efficient navigation and traversal of memory structures.

Overview

The Palace System implements a spatial metaphor for organizing and accessing notes, inspired by the memory palace technique. It provides hierarchical organizational structures (wings, rooms, drawers, halls) and traversal mechanisms (tunnels) that allow agents to navigate complex information spaces efficiently.

The system follows the architecture decision that the Vault serves as the source of truth while the Palace provides retrieval acceleration. This dual-layer design ensures data persistence alongside fast access patterns.

Sources: CLAUDE.md:3

Architecture

graph TD
    subgraph OMPA["OMPA Core"]
        subgraph VaultLayer["Vault Layer"]
            V[Vault - Source of Truth]
        end
        subgraph PalaceLayer["Palace Layer - Retrieval Acceleration"]
            W[Wings]
            R[Rooms]
            D[Drawers]
            H[Halls]
            T[Tunnels]
        end
    end
    U[User/Agent] --> API
    API[CLI / MCP / Python API]
    API --> PalaceLayer
    PalaceLayer --> VaultLayer

Core Components

Sources: README.md:1

Palace Metadata Storage

The Palace System uses SQLite for storing all metadata, with connections managed via context managers to prevent leaks. All temporal data supports validity windows, allowing the system to track how structures evolve over time.

# Temporal KG with validity windows
# From ompa/knowledge_graph.py pattern

The architecture follows lazy semantic loading principles, where palace structures are initialized on first access rather than at import time.

Sources: CLAUDE.md:3

Wing Management

Wings represent the top-level organizational units in the Palace System. Each wing can contain multiple rooms and serves as a primary navigation anchor.

Creating Wings

ao.palace.create_wing("Orion")

Listing Wings

wings = ao.palace.list_wings()

Wing Operations via CLI

ao wings  # List all palace wings

Sources: README.md:1 Sources: ompa/cli.py

Room Management

Rooms are sub-categories that belong to specific wings. They provide a second level of hierarchy for organizing palace structures.

Listing Rooms in a Wing

rooms = ao.palace.list_rooms("Orion")

Room Operations via CLI

ao rooms <wing>  # List rooms in a specific wing

Sources: README.md:1

Tunnel System

Tunnels enable cross-wing navigation, creating shortcuts between different wings of the palace. This allows agents to traverse between seemingly unrelated areas efficiently.

Creating Tunnels

ao.palace.create_tunnel(wing_a, wing_b, room="shared")

Tunnel Parameters

CLI Tunnel Command

ao tunnel  # Create/traverse cross-wing tunnel

Sources: README.md:1

MCP Server Integration

The Palace System is exposed via the MCP (Model Context Protocol) server, allowing integration with AI agents like Claude Code, Cursor, and Windsurf.

Available MCP Tools

MCP Configuration

{
  "mcpServers": {
    "ompa": {
      "command": "python",
      "args": ["-m", "ompa.mcp_server"],
      "env": {
        "OMPA_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

Sources: examples/mcp_desktop/README.md:1

CLI Commands

The Palace System can be accessed through the ao CLI utility:

# List all palace wings
ao wings

# List rooms in a specific wing
ao rooms <wing>

# Create or traverse a tunnel
ao tunnel

Sources: README.md:1

Integration with Core OMPA

The Palace System is instantiated as part of the main Ompa class:

from ompa import Ompa

ao = Ompa(vault_path="./workspace")
# Palace is available at ao.palace
wings = ao.palace.list_wings()

The Ompa class manages the lifecycle of the Palace instance, ensuring it shares the same vault path and configuration.

Sources: ompa/core.py:1

Statistics and Monitoring

The Palace System provides statistics about its current state:

# Via Python API
stats = ao.palace.stats()

# Via MCP
result = ao_palace_stats(vault_path)

# Via CLI (combined with vault and KG stats)
ao status

The status command returns a combined view of vault health, palace metadata, and knowledge graph statistics.

Sources: ompa/mcp_server.py:70-73

Data Flow

sequenceDiagram
    participant User
    participant CLI
    participant MCP
    participant Ompa
    participant Palace
    participant Vault
    participant SQLite
    
    User->>CLI: ao wings
    CLI->>Ompa: list_wings()
    Ompa->>Palace: list_wings()
    Palace->>SQLite: Query wings metadata
    SQLite-->>Palace: Wing list
    Palace-->>Ompa: Wing list
    Ompa-->>CLI: Wing list
    CLI-->>User: Display wings
    
    User->>MCP: ao_palace_rooms(wing="Orion")
    MCP->>Ompa: list_rooms("Orion")
    Ompa->>Palace: list_rooms()
    Palace->>SQLite: Query rooms WHERE wing="Orion"
    SQLite-->>Palace: Room list
    Palace-->>Ompa: Room list
    Ompa-->>MCP: Room list
    MCP-->>User: Display rooms

Design Principles

1. Vault + Palace Dual-Layer: The vault serves as the source of truth while the palace provides retrieval acceleration
2. Context Managers: All SQLite connections use with statements for leak-free operation
3. Lazy Initialization: Palace structures are loaded on first access rather than at import time
4. Temporal Support: Palace metadata supports validity windows for tracking structural changes over time

Sources: CLAUDE.md:3

See Also

• Vault System - Source of truth layer
• Knowledge Graph - Temporal triple storage
• Classifier - Message type classification and routing
• MCP Server Setup - Agent integration guide

Related Pages

Related topics: Three-Layer Architecture, Palace System

Knowledge Graph

The Knowledge Graph (KG) is a core temporal data storage component in OMPA that maintains structured relationships between entities using SQLite-backed triple storage. It enables agents to query historical information, track entity validity windows, and maintain a persistent memory of facts across sessions.

Overview

The Knowledge Graph stores facts as triples (subject, predicate, object) with temporal validity windows, allowing queries like "What was the state of X at time Y?" or "Show me all relationships involving entity Z."

Sources: CLAUDE.md

Architecture

graph TD
    A[Vault Notes] --> B[populate_from_vault]
    C[User Message] --> D[add_triple]
    B --> E[(SQLite DB)]
    D --> E
    E --> F[query_entity]
    E --> G[timeline]
    E --> H[get_predicates]
    E --> I[stats]
    F --> J[Triple Results]
    G --> K[Timeline View]
    I --> L[Statistics]

The KG operates as a layer above the vault, extracting structured data from unstructured notes and providing temporal query capabilities.

Sources: ompa/core.py:1-50

Core Data Model

Triple Structure

Each fact in the Knowledge Graph is stored as a triple with temporal metadata:

Temporal Validity Windows

The KG supports temporal reasoning through validity windows:

• Point-in-time facts: Both valid_from and valid_to set
• Current facts: Only valid_from set (open-ended)
• Historical facts: Both timestamps set to past dates

This enables queries like retrieving the state of relationships at any past point.

Sources: ompa/knowledge_graph.py

KnowledgeGraph API

Constructor

class KnowledgeGraph:
    def __init__(self, vault_path: str = "~/.ompa"):
        self.db_path = Path(vault_path) / "knowledge_graph.db"

Initializes the KG with a database path under the OMPA config directory. The SQLite database is created automatically on first access.

Sources: ompa/knowledge_graph.py

add_triple

Adds a new fact to the knowledge graph:

def add_triple(
    self,
    subject: str,
    predicate: str,
    object_: str,
    valid_from: str | None = None,
    source: str | None = None,
) -> Triple:

Example:

kg.add_triple(
    subject="Kai",
    predicate="works_on",
    object_="Orion",
    valid_from="2025-06-01",
    source="brain/people/Kai.md"
)

Sources: ompa/knowledge_graph.py

query_entity

Retrieves all triples involving a specific entity:

def query_entity(self, entity: str) -> list[Triple]:

Returns all triples where the entity appears as subject or object. Results are ordered by validity window.

timeline

Gets temporal history for an entity:

def timeline(self, entity: str) -> list[dict]:

Returns a chronological view of all facts involving the entity, including temporal metadata for each relationship.

get_predicates

Lists all relationship types in the graph:

def get_predicates(self, subject: str | None = None) -> list[str]:

stats

Returns knowledge graph statistics:

def stats(self) -> dict:

Returns:

populate_from_vault

Scans existing vault notes and extracts structured facts:

def populate_from_vault(self, vault_path: str) -> dict:

Extracts entities from:

• Frontmatter tags
• Folder paths
• [[wikilinks]] cross-references

This enables automatic KG initialization from existing note content.

Sources: README.md

MCP Server Integration

The Knowledge Graph is exposed through MCP tools for agent integration:

graph LR
    A[MCP Client] -->|ao_kg_add| B[Add Triple]
    A -->|ao_kg_query| C[Query Entity]
    A -->|ao_kg_stats| D[Get Stats]
    A -->|ao_kg_populate| E[Populate from Vault]
    B --> F[KnowledgeGraph]
    C --> F
    D --> F
    E --> F

Available MCP Tools

Sources: ompa/mcp_server.py:1-50

MCP Tool Implementation

def ao_kg_add(arguments: dict, vault_path: str = ".") -> dict:
    """Add a triple to the knowledge graph."""
    ao = Ompa(vault_path=vault_path, enable_semantic=False)
    ao.kg.add_triple(
        subject=arguments["subject"],
        predicate=arguments["predicate"],
        object_=arguments["object"],
        valid_from=arguments.get("valid_from"),
        source=arguments.get("source"),
        vault_path=vault_path,
    )
    return {"success": True, "added": f"{subject} --{predicate}--> {object_}"}

def ao_kg_stats(vault_path: str = ".") -> dict:
    """Get knowledge graph statistics."""
    ao = Ompa(vault_path=vault_path, enable_semantic=False)
    return ao.kg.stats()

Sources: ompa/mcp_server.py:50-100

Usage Examples

Python API

from ompa import Ompa

ao = Ompa(vault_path="./workspace")

# Add facts
ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
ao.kg.add_triple("Orion", "has_status", "active")
ao.kg.add_triple("Kai", "reports_to", "Sarah")

# Query entity
triples = ao.kg.query_entity("Kai")
# Returns: [Triple(subject='Kai', predicate='works_on', object_='Orion', ...), ...]

# Get timeline
timeline = ao.kg.timeline("Kai")
# Returns chronological history of all Kai-related facts

# Get statistics
stats = ao.kg.stats()
# Returns: {'total_triples': 3, 'unique_subjects': 2, 'unique_predicates': 3, ...}

CLI Usage

# Query entity in knowledge graph
ao kg-query Kai

# Get entity timeline
ao kg-timeline Orion

# Get knowledge graph statistics
ao kg-stats

MCP Integration

In Claude Desktop or Cursor, the KG tools are available as:

{
  "mcpServers": {
    "ompa": {
      "command": "python",
      "args": ["-m", "ompa.mcp_server"],
      "env": {
        "OMPA_VAULT_PATH": "/absolute/path/to/vault"
      }
    }
  }
}

Sources: examples/mcp_desktop/README.md

Relationship to Other Components

graph TD
    subgraph OMPA Core
        A[Ompa Class] --> B[KnowledgeGraph]
        A --> C[Vault]
        A --> D[SemanticIndex]
        A --> E[Palace]
    end
    
    B --> F[(SQLite DB)]
    C --> G[Markdown Notes]
    D --> H[Sentence Embeddings]
    E --> I[Metadata Cache]
    
    J[MCP Server] --> B
    J --> C
    J --> D
    J --> E

The Knowledge Graph complements the vault by adding structure to unstructured note content.

Sources: ompa/core.py:1-100

Security Considerations

• Path traversal guards: All vault file operations resolve and boundary-check paths
• SQLite isolation: Each KG instance uses separate database file
• Source tracking: Every triple records its source note for auditability

Sources: CHANGELOG.md

Changelog

Sources: CHANGELOG.md

Related Pages

Related topics: Vault System, Python API Reference

Message Classification

Message Classification is a core feature of OMPA that automatically categorizes incoming messages into 15 distinct types and routes them to appropriate locations within the vault structure. This system enables intelligent, automated memory management for AI agents working across different contexts.

Overview

The classifier uses regex pattern matching to identify message types based on linguistic cues, then provides routing hints to guide content placement. It integrates deeply with the vault architecture, suggesting target folders and actions for each classified message type.

Sources: ompa/classifier.py:1-50

Architecture

graph TD
    A[Incoming Message] --> B[Classifier.classify]
    B --> C{Pattern Matching}
    C -->|Decision| D[MessageType.DECISION]
    C -->|Incident| E[MessageType.INCIDENT]
    C -->|Meeting| F[MessageType.MEETING]
    C -->|Win| G[MessageType.WIN]
    C -->|...| H[Other Types]
    
    D --> I[Routing Hints]
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J[Suggested Folder]
    I --> K[Suggested Action]
    
    J --> L[Vault Storage]
    K --> M[Knowledge Graph]

Sources: ompa/classifier.py:60-120

Message Types

OMPA defines 15 distinct MessageType values for classifying different kinds of agent communications:

Sources: ompa/classifier.py:1-30 Sources: CLAUDE.md:1-20

Pattern Matching System

The classifier uses regex patterns to identify message types. Each MessageType has an associated list of regex patterns:

PATTERNS = {
    MessageType.DECISION: [
        r"\b(decided|decision|made a choice|going with|settled on|agreed to)\b",
        r"\b(defer|postpone|push to|revisit)\b.*\b(Q\d|quarter|sprint)\b",
        r"(?:ADR|decision record)",
    ],
    MessageType.INCIDENT: [
        r"\b(incident|outage|bug|crash|failure|error|broken)\b",
        r"\b(debug|root cause|RCA|mitigation|hotfix)\b",
        r"(?:on-call|pagerduty|statuspage)",
    ],
    MessageType.WIN: [
        r"\b(won|praised|success|achieved|shipped|launched|deployed)\b",
        r"\b(great work|nice job|excellent|well done)\b",
        r"\b(milestone|feature complete|released)\b",
    ],
    # ... additional patterns
}

Sources: ompa/classifier.py:30-100

Pattern Priority

Patterns are evaluated in order, and the first matching pattern determines the message type. This allows for specific patterns to take precedence over general ones.

Routing Hints

Each message type includes ROUTING_HINTS that provide guidance on how to handle classified content:

ROUTING_HINTS = {
    MessageType.DECISION: [
        "This is a decision. Record it in brain/Key Decisions.md",
        "Update relevant project notes with the decision",
        "Add to Decision Log if formal ADR needed",
    ],
    MessageType.INCIDENT: [
        "Create incident note in work/incidents/",
        "Run /om-incident-capture for structured capture",
        "Update brain/Gotchas.md with lessons learned",
    ],
    MessageType.WIN: [
        "Add to perf/Brag Doc.md immediately",
        "This is a win worth capturing for performance review",
        "Update relevant competency notes with evidence",
    ],
    # ... additional hints
}

Sources: ompa/classifier.py:100-180

Classification API

Core Classification Method

from ompa.classifier import Classifier, Classification

classifier = Classifier()
result: Classification = classifier.classify("We decided to go with Postgres")

Return Type

The classify() method returns a Classification object containing:

Sources: ompa/classifier.py:120-150 Sources: STABILITY.md:10-20

Dual-Vault Integration

When running in dual-vault mode, the classifier also supports content classification for vault routing:

from ompa.config import DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)

target = config.classify_content(content, tags=tags, file_path=path)

Sources: ompa/core.py:50-80

Classification Factors

Content is classified to shared or personal vaults based on:

1. Content analysis - Keywords indicating personal vs. work content
2. Tags - Frontmatter tags that may indicate classification
3. File path - Existing location hints in vault structure

Adding Custom Message Types

To extend the classifier with new message types, follow this process:

Step 1: Add Enum Value

# ompa/classifier.py
class MessageType(str, Enum):
    # ... existing types
    YOUR_NEW_TYPE = "your_new_type"

Step 2: Add Regex Patterns

PATTERNS[MessageType.YOUR_NEW_TYPE] = [
    r"\b(keyword1|keyword2)\b",
    r"\b(phrase pattern)\b",
]

Step 3: Add Routing Hints

ROUTING_HINTS[MessageType.YOUR_NEW_TYPE] = [
    "Action hint 1",
    "Action hint 2",
]

Step 4: Add Folder Mapping

FOLDER_MAP[MessageType.YOUR_NEW_TYPE] = "brain/your-type/"

Step 5: Add Tests

# tests/test_ompa.py
class TestClassifier:
    def test_your_new_type(self):
        # Add test cases

Sources: CONTRIBUTING.md:20-40

CLI Integration

The classifier is accessible via the CLI:

# Classify a single message
ao classify "We decided to go with Postgres"

# Classify with context
ao classify "The deployment failed with a timeout error"

MCP Tools

The following MCP tools expose classification functionality:

Sources: ompa/mcp_server.py:1-30

Confidence Scoring

The classifier assigns confidence scores based on:

1. Pattern match count - More pattern matches = higher confidence
2. Pattern specificity - More specific patterns score higher
3. Keyword density - Higher density of type-specific keywords

Confidence is normalized to a 0.0-1.0 range for downstream processing.

Extensibility Points

The classification system can be extended through:

1. Custom patterns - Add regex patterns per message type
2. Custom routing hints - Extend action suggestions
3. Custom folders - Define target locations per type
4. Hook integration - Execute hooks on classification events

Sources: CLAUDE.md:30-50

Data Flow

sequenceDiagram
    participant User
    participant CLI as CLI/API
    participant Classifier
    participant Vault
    participant KG as Knowledge Graph
    
    User->>CLI: ao classify "message"
    CLI->>Classifier: classify(message)
    Classifier->>Classifier: Pattern matching
    Classifier-->>CLI: Classification result
    CLI-->>User: Type + routing hints
    
    User->>CLI: ao handle_message "message"
    CLI->>Classifier: classify(message)
    Classifier-->>CLI: Classification + folder
    CLI->>Vault: Save to suggested folder
    CLI->>KG: Add extracted entities
    Vault-->>CLI: Note saved
    KG-->>CLI: Triples added

This comprehensive classification system enables OMPA to automatically organize agent communications, maintain structured memory, and provide intelligent routing for all types of work content.

Related Pages

Related topics: Lifecycle Hooks

Python API Reference

The Python API provides programmatic access to OMPA's core functionality, enabling integration with AI agents, custom workflows, and external applications. The API is designed around the Ompa class as the primary entry point, offering lifecycle management, semantic search, knowledge graph operations, and dual-vault isolation.

Doramagic Pitfall Log

Doramagic extracted 11 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: OMPA v0.2.0 — The Big Rename

• Severity: medium
• Finding: Installation risk is backed by a source signal: OMPA v0.2.0 — The Big Rename. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/jmiaie/ompa/releases/tag/v0.2.0

2. Configuration risk: [P0] agent_integration.py race condition — session.memory attribute not available on cold start

• Severity: medium
• Finding: Configuration risk is backed by a source signal: [P0] agent_integration.py race condition — session.memory attribute not available on cold start. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/jmiaie/ompa/issues/6

3. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass.

4. Project risk: I did an analysis of 44 AI agent frameworks, sharing the result

• Severity: medium
• Finding: I did an analysis of 44 AI agent frameworks, sharing the result 18 Feb 2026 · One thing missing from most framework comparisons is how they handle failures during agent execution. Tool call retries, error recovery, and ...
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: social_signal:reddit | ssig_33233a78090343098fbddbeab9bc927d | https://www.reddit.com/r/LocalLLaMA/comments/1r84o6p/i_did_an_analysis_of_44_ai_agent_frameworks/ | I did an analysis of 44 AI agent frameworks, sharing the result

5. Project risk: Your self-hosted AI agents can match closed-source models - I ... - Reddit

• Severity: medium
• Finding: Your self-hosted AI agents can match closed-source models - I ... - Reddit 24 Nov 2025 · Looking for open-source knowledge management tool ... Let's compare 5 Open-Source AI Agent Tools that everyone cannot stop talking about on Reddit.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: social_signal:reddit | ssig_4fefa11ceedb46d4af5e2ff44e7709e1 | https://www.reddit.com/r/selfhosted/comments/1p5q8f1/your_selfhosted_ai_agents_can_match_closedsource/ | Your self-hosted AI agents can match closed-source models - I ... - Reddit

6. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing

7. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium

8. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium

9. Security or permission risk: OMPA v0.2.1 — Security & Reliability Hardening

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: OMPA v0.2.1 — Security & Reliability Hardening. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/jmiaie/ompa/releases/tag/v0.2.1

10. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown

11. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ompa with real data or production workflows.

• [[P0] agent_integration.py race condition — session.memory attribute not](https://github.com/jmiaie/ompa/issues/6) - github / github_issue
• OMPA v0.2.1 — Security & Reliability Hardening - github / github_release
• OMPA v0.2.0 — The Big Rename - github / github_release
• Anybody who tried Hermes-Agent? : r/LocalLLaMA - Reddit - reddit / searxng_indexed
• 100+ agentic skills, commands, and plugins for PMs. Designed for ... - x / searxng_indexed
• Your self-hosted AI agents can match closed-source models - I ... - Redd - reddit / searxng_indexed
• I built a free MCP server with Claude Code that gives Claude a Jira-like - reddit / searxng_indexed
• I did an analysis of 44 AI agent frameworks, sharing the result - reddit / searxng_indexed
• Zero-human company tech Open-source AI Agent orchestration ... - x / searxng_indexed
• README/documentation is current enough for a first validation pass. - GitHub / issue