OMPA

Universal AI Agent Memory Layer

Vault · Palace · Temporal Knowledge Graph

Obsidian-MemPalace-Agnostic — Give any AI agent persistent memory in one pip install. Works with Claude Code, OpenClaw, Codex, Gemini CLI, LangChain, or any custom agent.

pip install ompa
ao init && ao session-start

96.6% R@5 on LongMemEval using verbatim storage — no summarization loss, no API cost for search.

Why OMPA?

Every AI agent starts empty every session. Important decisions get lost. Context grows expensive. Summaries lose nuance.

OMPA solves all three:

Three-Layer Architecture

flowchart TB
    agent(["🤖 AI Agent"])

    subgraph vault["Layer 1 · Vault"]
        v["brain/ · work/ · org/ · perf/\nhuman-navigable markdown notes"]
    end

    subgraph palace["Layer 2 · Palace"]
        p["wings → rooms → drawers\nhalls · facts · events · tunnels"]
    end

    subgraph kg["Layer 3 · Knowledge Graph"]
        k["subject → predicate → object\nSQLite · validity windows · timeline"]
    end

    agent <-->|"session_start · user_message · stop"| vault
    vault <--> palace
    palace <--> kg

Quick Start

1. Install

pip install ompa          # Core only
pip install ompa[all]     # Includes local semantic search

2. Initialize a vault

ao init              # Create vault structure
ao status            # Verify everything looks good

3. Use in a session

ao session-start                              # ~2K token context injection
ao classify "We decided to go with Postgres"  # Routes to right folder automatically
ao search "authentication decisions"          # Local semantic search, zero API cost
ao kg-query Kai                               # Query the knowledge graph
ao wrap-up                                    # Session summary + save to vault

4. Python API

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.stop()

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

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

# Palace navigation
ao.palace.create_wing("Orion", type="project")
ao.palace.create_tunnel("Kai", "Orion", "auth-migration")

Features

5 Lifecycle Hooks

15 Message Types

Auto-classified and routed to the right vault folder:

DECISION · INCIDENT · WIN · LOSS · BLOCKER · QUESTION · SUGGESTION · REVIEW · BUG · FEATURE · LEARN · RETROSPECTIVE · ALERT · STATUS · CHORE

ao classify "We decided to go with Postgres over MySQL"
# → MessageType.DECISION → vault/work/decisions/2026-05-07-postgres.md

MCP Server (15 Tools)

Plug directly into Claude Desktop, Cursor, or Windsurf with one command:

claude mcp add ompa -- python -m ompa.mcp_server

Dual-Vault Mode

Isolate team/org content from personal or private notes:

from ompa import Ompa, DualVaultConfig, IsolationMode

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

CLI Reference

ao init              Initialize a new vault
ao status            Health check and stats (shows installed vs latest version)
ao session-start     Inject memory context (use at session start)
ao classify <msg>    Classify and route a message
ao search <query>    Semantic search
ao orphans           Detect orphaned notes
ao wrap-up           Session summary and save
ao wings             List palace wings
ao rooms <wing>      List rooms in a wing
ao tunnel            Create/traverse cross-wing tunnel
ao kg-query <entity> Query knowledge graph
ao kg-timeline <e>   Entity timeline
ao kg-stats          Knowledge graph statistics
ao validate          Validate vault structure
ao rebuild-index     Rebuild the semantic index
ao upgrade           Upgrade ompa to the latest version from PyPI
ao doctor            Full health check table (version, vault, KG, index, orphans)
ao migrate-vault     Apply pending vault schema migrations

Framework Compatibility

Comparison

Installation Options

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

# With local semantic search (adds sentence-transformers + numpy)
pip install ompa[all]

# Development
pip install ompa[dev]

# From source
git clone https://github.com/jmiaie/MicapAiLabs && cd MicapAiLabs/ompa
pip install -e ".[all]"

Requires Python 3.10+.

Package 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)

Credits & Attribution

OMPA is a synthesis of ideas from the AI agent memory community:

• MemPalace by Kyle Corbitt — palace metaphor (wings/rooms/drawers), temporal KG design, and verbatim storage approach (96.6% R@5 on LongMemEval)
• obsidian-mind — vault structure (brain/work/org/perf), wikilink conventions, frontmatter validation, session lifecycle patterns
• Claude Code / Anthropic — hook patterns and agent-tool interaction models
• OpenClaw — framework-agnostic agent runtime that inspired the "universal" design goal

License

MIT — Micap AI