Gomaa 🧠

Production-grade, local-first hierarchical memory engine for autonomous AI agents.

Gomaa equips AI agents (Hermes, OpenClaw, OpenManus, Claude Desktop, Cursor, Windsurf, CrewAI, LangChain) with permanent, structured long-term memory. It bridges human-readable Obsidian Markdown Vaults with high-speed PostgreSQL + pgvector (HNSW) or zero-config SQLite, powering hybrid Reciprocal Rank Fusion (RRF) search, wikilink knowledge graphs, Ebbinghaus temporal decay, cross-agent fleet sharing, and asynchronous Google Drive cloud synchronization.

📑 Table of Contents

• ⚡ Complete Feature Matrix
• 🏗️ System Architecture
• 🧠 Deep Dive into Key Capabilities
  • 1. Hierarchical Wing & Room Taxonomy
  • 2. Hybrid Reciprocal Rank Fusion (RRF) Search
  • 3. Cross-Agent Shared Memory Layer (shared_db)
  • 4. Ebbinghaus Temporal Decay & Pinned Immunity
  • 5. Obsidian Markdown Vault & Bi-Directional Graph
  • 6. Turn-Aware Verbatim Session Ingestor
  • 7. Asynchronous Google Drive Cloud Synchronization
  • 8. Flexible Embedding Backends (FastEmbed / Microservice / Local)
  • 9. Defense-in-Depth Security & Injection Armor
• 🛠️ MCP Tool Reference (9 Tools)
• 🌐 Multi-Agent Fleet Production Architecture
• 🚀 Quick Start & Installation
• 🤖 Agent Framework Integration Recipes
• 💻 Complete CLI Command Reference
• ⚙️ Environment Variables Reference
• 🧪 Testing & Benchmarks
• 📄 License

⚡ Complete Feature Matrix

🏗️ System Architecture

                                ┌──────────────────────────────────────────────┐
                                │          AI Agents & LLM Frameworks          │
                                │  Hermes • OpenClaw • Claude • Cursor • Manus │
                                └──────────────────────┬───────────────────────┘
                                                       │ JSON-RPC (stdio) / Python SDK
                                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                           Gomaa Core (v3.4.0)                                           │
│                                                                                                             │
│  ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────────────────────────┐  │
│  │ Admission & Security    │  │ Multi-Backend Embedder  │  │ Turn-Aware Session Ingestor                 │  │
│  │ - Secret Regex Guard    │  │ - FastEmbed (ONNX 30MB) │  │ - Turn boundary splitting                   │  │
│  │ - Injection Neutralizer │  │ - Remote Microservice   │  │ - 1500-char linear sliding window           │  │
│  │ - Path Traversal Guard  │  │ - SentenceTransformers  │  │ - Sequential [[Wiki Link]] chaining         │  │
│  └─────────────────────────┘  └─────────────────────────┘  └─────────────────────────────────────────────┘  │
│                                                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                                 Hybrid RRF Retrieval & Graph Ranker                                   │  │
│  │            RRF Score = 1.0 * Dense(HNSW) + 0.8 * Keyword(FTS) + 0.6 * Graph + 0.2 * Salience          │  │
│  └───────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────┬───────────────────────────────────────┬─────────────────────────────┘
                                        │                                       │
                ┌───────────────────────┴───────────────────────┐               │
                ▼                                               ▼               ▼
 ┌─────────────────────────────┐                 ┌─────────────────────────────────────────────┐
 │    PostgreSQL + pgvector    │                 │       Obsidian Markdown Vault (Local)       │
 │ - HNSW vector_cosine_ops    │                 │ - Human-Readable Markdown + YAML Frontmatter │
 │ - GIN tsvector English FTS  │                 │ - [[Wikilink]] Knowledge Graph Visualizer   │
 │ - Self-Healing DB Pool      │                 │ - Atomic Writes with EXDEV Fallback         │
 │ - Private DB + shared_db    │                 └──────────────────────┬──────────────────────┘
 └─────────────────────────────┘                                        │ Async Background Sync
                                                                        ▼
                                                 ┌─────────────────────────────────────────────┐
                                                 │              Google Drive Cloud             │
                                                 │ - Service Account / OAuth2 Authentication    │
                                                 │ - MD5 Checksum Verification                 │
                                                 │ - Sibling .conflict-TIMESTAMP.md Resolution │
                                                 └─────────────────────────────────────────────┘

🧠 Deep Dive into Key Capabilities

1. Hierarchical Wing & Room Taxonomy

Memory cross-contamination is a major failure mode in multi-agent fleets. Gomaa structures memory as a 2-level physical palace:

• wing (Domain/Project): Top-level domain boundary (e.g. ecommerce, pentest, devops, shared).
• room (Topic/Channel): Granular topic partition (e.g. database, firewall, stripe_api).

Queries can be scoped tightly to a specific wing or room, preventing marketing prompts from recalling penetration testing findings.

2. Hybrid Reciprocal Rank Fusion (RRF) Search

Standard vector search fails on exact technical strings (e.g. CVE-2024-38077, 0x7fff5fbff8c0), while keyword search fails on semantic concepts. Gomaa executes multi-candidate retrieval and merges results using weighted RRF:

$$\text{RRF Score}(d) = \sum_{m \in \text{modes}} w_m \cdot \frac{1}{k + \text{rank}_m(d)} + 0.2 \cdot \text{Salience}(d)$$

• Dense HNSW Vector Search: Weight $1.0$ (Cosine distance over 384-dimensional embeddings).
• PostgreSQL Full-Text Search: Weight $0.8$ (tsvector weighted with title as A and content as B).
• Recursive Graph Traversal: Weight $0.6$ (Recursive CTE discovering 1-hop and 2-hop [[Wiki Links]]).
• Memory Salience Engine: Weight $0.2$ (Importance score from $0.0$ to $1.0$).

3. Cross-Agent Shared Memory Layer (shared_db)

In autonomous multi-agent environments, agents maintain isolated private databases (toy_db, old_db, candy_db, etc.) to prevent state corruption. However, collective intelligence requires sharing global policies and verified facts.

• Publishing: Using memory_publish_shared, vetted notes are published to shared_db.
• Credential Screening: Content is scanned against strict regex filters for Anthropic keys (sk-ant-), Google Gemini keys (AIza...), HuggingFace tokens (hf_...), OpenAI keys (sk-proj-...), AWS access keys (AKIA...), Slack tokens (xox-), and private keys.
• Fail-Soft Recall: When an agent queries memory, memory_recall queries both the private store and shared_db. If the shared database is temporarily unreachable, it degrades gracefully without interrupting the agent.

4. Ebbinghaus Temporal Decay & Pinned Immunity

Memories naturally lose relevance over time. Gomaa implements Herman Ebbinghaus's exponential forgetting curve:

$$\text{Salience}(t) = \text{Salience}0 \times (0.95)^{\Delta t{\text{days}}}$$

• Touch Feedback: Accessing a memory updates last_accessed_at, resetting its decay.
• Nightly Auto-Archiving: Consolidation automatically transitions notes with $\text{Salience} < 0.05$ and unaccessed for $>90\text{ days}$ to status = 'archived'.
• Pinned Immunity: System rules, core policies, or notes marked with pinned=True or tagged #pinned receive permanent immunity from temporal decay ($\text{Salience} = 1.0$).

5. Obsidian Markdown Vault & Bi-Directional Graph

Every memory created by an agent is simultaneously written as a human-readable .md file inside your Obsidian vault:

• Zettelkasten Frontmatter: Contains title, date, tags, type, salience, wing, and room.
• Knowledge Graph: Target notes mentioned as [[Target Note]] are automatically parsed into bi-directional edges in PostgreSQL.
• Live Inspection: Open Obsidian on your desktop or mobile device and explore your agent fleet's collective memory in Obsidian's interactive Graph View.

6. Turn-Aware Verbatim Session Ingestor

Conversational transcripts often contain crucial nuances lost in lossy summarization. memory_ingest_session:

• Splits raw transcripts along turn boundaries (User:, Assistant:, ### Turn, **Human**:).
• For turns longer than 1,500 characters, applies a linear sliding window (1,500 chars with 200-char overlap).
• Chains sequential chunks using [[Session ... Turn 01 Part 02]] wikilinks, preserving code blocks, execution traces, and conversational flow.

7. Asynchronous Google Drive Cloud Synchronization

Keep your agent vaults securely backed up and synchronized across multiple machines or mobile devices:

• Local-First Speed: Agent tool calls execute at local SSD speeds (<1ms) without blocking on Google Drive network latency.
• Background Daemon / Cron Sync: Scans vault files, computes MD5 checksums, and synchronizes deltas bidirectionally with Google Drive.
• Conflict Resolution: If a file is modified on both Google Drive and the local agent vault simultaneously, Gomaa saves the incoming version as NoteName.conflict-YYYYMMDD-HHMMSS.md, preventing data loss.
• Authentication: Supports Google Cloud Service Account JSON (GOOGLE_APPLICATION_CREDENTIALS, GDRIVE_SERVICE_ACCOUNT_JSON) and OAuth2 user tokens (GDRIVE_TOKEN_JSON).

8. Flexible Embedding Backends (FastEmbed / Microservice / Local)

Gomaa adapts to any deployment resource budget:

1. FastEmbed ONNX Runtime (Recommended for Standalone Nodes): Uses ONNX Runtime C++ execution (~30MB RAM). Zero PyTorch overhead.
2. Centralized Microservice (gomaa.embed_service): Hosts sentence-transformers in a single dedicated container serving multiple agent containers over HTTP (MEMORY_EMBED_URL).
3. Local SentenceTransformers: Standalone PyTorch execution (all-MiniLM-L6-v2, 384-dimensional).
4. Deterministic Hash Fallback: Zero-RAM mathematical vector hash for ultra-constrained environments.

9. Defense-in-Depth Security & Injection Armor

• Path Traversal Immunity: Dual-resolved canonical path checks (is_relative_to) ensure file operations cannot escape the vault root.
• Atomic Sibling Writes: Files are written to sibling temporary files (.note.pid.tmp) and renamed atomically, with automatic fallback for EXDEV cross-device volume mounts.
• Control Token Neutralization: Neutralizes LLM injection tokens (<|im_start|>, <|system|>, [INST], <<SYS>>) in prose while preserving code blocks verbatim.
• Structured XML Context Enclosure: Recalled memories are wrapped in <recalled_memory_context id="..." title="..." source="..."> tags with internal tag escaping, ensuring host LLMs never confuse recalled memories with active system directives.

🛠️ MCP Tool Reference (8 Tools)

All 8 tools are natively exposed to agents over standard MCP JSON-RPC stdio:

1. memory_remember

Store a private memory note in the vault with semantic embedding, tags, and hierarchical scoping.

{
  "title": "PostgreSQL HNSW Tuning",
  "content": "For datasets >10,000 vectors, use HNSW with m=16 and ef_construction=64 for optimal recall.",
  "tags": ["database", "pgvector", "performance"],
  "wing": "engineering",
  "room": "databases",
  "salience": 0.8,
  "pinned": true
}

2. memory_publish_shared

Publish a sanitized, vetted finding or policy to the cross-agent shared fleet memory (shared_db).

{
  "title": "Fleet Security Policy: SSL Verification",
  "content": "All internal agent HTTP requests must enforce SSL certificate validation.",
  "tags": ["security", "policy"],
  "wing": "shared",
  "room": "general"
}

3. memory_recall

Search memories across private and shared fleet databases using hybrid RRF, HNSW vectors, keywords, or graph.

{
  "query": "HNSW index configuration parameters",
  "mode": "hybrid",
  "top_k": 5,
  "scope": {
    "wing": "engineering",
    "room": "databases"
  },
  "include_shared": true
}

4. memory_ingest_session

Ingest and chunk a complete conversation transcript verbatim along turn boundaries.

{
  "transcript": "User: How do we configure pgvector?\nAssistant: Use CREATE EXTENSION vector; then create an HNSW index.",
  "wing": "engineering",
  "room": "sessions"
}

5. memory_timeline

Inspect recent memory operations (remember, recall, remind, consolidate) in chronological order.

{
  "limit": 20
}

6. memory_history

View version history and past edit snapshots of a specific memory note before updates.

{
  "title": "PostgreSQL HNSW Tuning",
  "limit": 5
}

7. memory_remind_me

Schedule a future prospective reminder or recurring task.

{
  "title": "Rotate Database Credentials",
  "content": "Verify that all 5 agent connection pools are refreshed with new passwords.",
  "trigger_at": "2026-09-01T00:00:00Z",
  "recurring": "monthly"
}

8. memory_assemble_context

Retrieve, rank, and pack high-salience memories into a strict token-budgeted XML prompt block ready for direct LLM system prompt injection.

{
  "query": "Kubernetes staging deployment limits",
  "max_tokens": 1500,
  "mode": "hybrid",
  "scope": {
    "wing": "infrastructure"
  },
  "include_shared": true
}

9. memory_audit

Get real-time memory health metrics, store backend status, request counts, and active wings.

{}

🌐 Multi-Agent Fleet Production Architecture

In multi-agent production setups (such as the 5-agent Hermes fleet), Gomaa isolates agent databases on an internal Docker network while providing shared intelligence:

                                  ┌─────────────────────────────────────────┐
                                  │      Production VPS (${VPS_HOST})      │
                                  └────────────────────┬────────────────────┘
                                                       │
         ┌───────────────────┬──────────────────┼───────────────────┬──────────────────┐
         ▼                   ▼                  ▼                   ▼                  ▼
┌──────────────────┐┌──────────────────┐┌──────────────────┐┌──────────────────┐┌──────────────────┐
│   hermes-agent   ││ hermes-assistant ││ hermes-marketing ││  hermes-pentest  ││  hermes-trader   │
│      (Toy)       ││      (Old)       ││     (Candy)      ││     (Pencil)     ││      (Coin)      │
│   Database:      ││   Database:      ││   Database:      ││   Database:      ││   Database:      │
│     toy_db       ││     old_db       ││     candy_db     ││     pencil_db    ││     trader_db    │
└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘
         │                   │                  │                   │                  │
         └───────────────────┴──────────────────┼───────────────────┴──────────────────┘
                                                │
                                                ▼
                               ┌───────────────────────────────────┐
                               │   PostgreSQL + pgvector (HNSW)    │
                               │   - Private DBs: toy_db, old_db.. │
                               │   - Shared DB:   shared_db        │
                               └───────────────────────────────────┘

🚀 Quick Start & Installation

1. Installation

# Standard installation
pip install gomaa

# With Google Drive Cloud Synchronization support
pip install "gomaa[gdrive]"

# With lightweight FastEmbed ONNX support (~30MB RAM)
pip install "gomaa[fastembed]"

# Full installation (All extras + Dev dependencies)
pip install "gomaa[dev,gdrive,fastembed,embed-service]"

2. Run with Docker Compose

Start the PostgreSQL + pgvector container:

docker compose up -d

3. Launch MCP Server

# Standalone with local SQLite (Zero configuration)
python -m gomaa server

# With PostgreSQL + pgvector
MEMORY_DB_DSN="postgresql://mnemosyne:***@localhost:5432/my_agent_db" python -m gomaa server

🤖 Agent Framework Integration Recipes

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "gomaa": {
      "command": "python3",
      "args": ["-m", "gomaa", "server"],
      "env": {
        "MEMORY_VAULT_PATH": "/Users/username/Documents/Obsidian/AgentVault",
        "MEMORY_DEFAULT_WING": "claude"
      }
    }
  }
}

2. Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "gomaa": {
      "command": "python3",
      "args": ["-m", "gomaa", "server"],
      "env": {
        "MEMORY_VAULT_PATH": "./.vault",
        "MEMORY_DEFAULT_WING": "codebase"
      }
    }
  }
}

3. Hermes Agent (~/.hermes/config.yaml)

mcp_servers:
  obsidian_memory:
    command: python3
    args: ["-m", "gomaa", "server"]
    env:
      MEMORY_DB_DSN: "postgresql://mnemosyne:***@${DB_HOST}:5432/toy_db"
      MEMORY_SHARED_DSN: "postgresql://mnemosyne:***@${DB_HOST}:5432/shared_db"
      MEMORY_VAULT_PATH: "/opt/data/vault"

4. OpenClaw (openclaw-config.yaml)

plugins:
  mcp_servers:
    mnemosyne:
      command: "python3"
      args: ["-m", "gomaa", "server"]
      env:
        MEMORY_VAULT_PATH: "~/.openclaw/vault"
        MEMORY_DEFAULT_WING: "openclaw"

5. LangChain & LangGraph

Drop-in memory adapter using Gomaa's token-budgeted prompt context assembler:

from gomaa.adapters.langchain import GomaaMemory
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI

memory = GomaaMemory(
    wing="support_agent",
    room="tickets",
    max_tokens=1500
)

conversation = ConversationChain(
    llm=ChatOpenAI(model="gpt-4o"),
    memory=memory,
    verbose=True
)
conversation.predict(input="Our PostgreSQL server is at 10.0.0.5 on port 5432.")

6. CrewAI Multi-Agent Swarms

Domain-isolated memory handler for CrewAI agents:

from gomaa.adapters.crewai import GomaaMemoryHandler
from crewai import Agent, Crew, Task

mem_handler = GomaaMemoryHandler(crew_name="security_squad")

agent = Agent(
    role="Penetration Tester",
    goal="Discover vulnerabilities in staging infrastructure",
    memory=True
)

# Save task findings with automatic domain wing isolation
mem_handler.save(
    value="Port 8080 open on staging host 10.0.0.5 running vulnerable Tomcat",
    metadata={"task": "recon", "salience": 0.9, "pinned": True},
    agent_role="Penetration Tester"
)

7. Python SDK & Autonomous Agent Scripts

from gomaa import UnifiedMemorySystem

mem = UnifiedMemorySystem(
    vault_path="~/.agent/vault",
    dsn="postgresql://mnemosyne:***@localhost:5432/agent_db",
    shared_dsn="postgresql://mnemosyne:***@localhost:5432/shared_db"
)

# Remember fact
mem.remember(
    title="Kubernetes Cluster Policy",
    content="Deployments in staging must specify resource memory limits.",
    wing="infrastructure",
    room="k8s",
    tags=["kubernetes", "policy"],
    pinned=True
)

# Assemble token-budgeted context for LLM prompt
ctx = mem.assemble_context(
    query="staging memory limits",
    max_tokens=1500,
    scope={"wing": "infrastructure"}
)
print(ctx["context_text"])

💻 Complete CLI Command Reference

Gomaa includes a full-featured management CLI:

# 1. Initialize local vault & generate ready-to-copy MCP configurations
gomaa init --path ~/.gomaa/vault

# 2. Launch interactive Aurora Web Knowledge Graph Dashboard
gomaa dashboard --port 8765

# 3. Store a memory note
gomaa remember "API Architecture" "Uses Bearer JWT auth." --tags security auth --wing backend --room api --salience 0.8 --pinned

# 4. Publish shared fleet memory
gomaa publish-shared "Global Production Policy" "Always check SSL certs." --wing devops

# 5. Search memories (hybrid / semantic / keyword / graph)
gomaa recall "JWT authentication" --mode hybrid --top-k 5 --wing backend

# 6. Assemble token-budgeted prompt context block
gomaa assemble-context "production policy" --max-tokens 1500 --wing devops

# 7. View activity timeline
gomaa timeline --limit 20

# 8. Trigger Ebbinghaus decay & link reconciliation
gomaa consolidate --decay-rate 0.95 --archive-threshold 0.05

# 9. Check system statistics & health
gomaa stats

# 10. Synchronize with Google Drive (One-off pass or daemon mode)
gomaa sync-gdrive --folder "My-Agent-Vault" --credentials service-account.json
gomaa sync-gdrive --daemon --interval 60

# 11. Run standalone Centralized Embedding Microservice
gomaa embed-service --host 0.0.0.0 --port 8000 --model all-MiniLM-L6-v2

⚙️ Environment Variables Reference

🧪 Testing & Benchmarks

📊 Performance Benchmark Scorecard

Benchmarked on Apple Silicon (M-series) / Ubuntu 24.04 LTS against a live knowledge graph of notes with 384-dimensional vector embeddings:

🔬 Test Suite Coverage (94 / 94 Passed · 100%)

Gomaa maintains a comprehensive automated test suite spanning 28 test modules:

collected 94 items
tests/test_adapters.py ..                                                [  2%]
tests/test_assemble_context.py ...                                       [  5%]
tests/test_chunking.py .                                                 [  6%]
tests/test_cli_init.py ..                                                [  8%]
tests/test_compat.py ....                                                [ 12%]
tests/test_consolidation.py ..                                           [ 14%]
tests/test_dashboard.py ......                                           [ 21%]
tests/test_embedder.py ...                                               [ 24%]
tests/test_embedder_offline.py .                                         [ 25%]
tests/test_embedder_v32.py ..                                            [ 27%]
tests/test_fts_websearch.py .                                            [ 28%]
tests/test_gdrive_safe_path.py .....                                     [ 34%]
tests/test_gdrive_sync.py ...                                            [ 37%]
tests/test_graph_cycles.py .                                             [ 38%]
tests/test_injection_defense.py ...                                      [ 41%]
tests/test_integration.py ...                                            [ 44%]
tests/test_mcp.py ..                                                     [ 46%]
tests/test_mcp_edge_cases.py ..                                          [ 48%]
tests/test_mcp_server.py ..............                                  [ 63%]
tests/test_reconcile_links.py .                                          [ 64%]
tests/test_remind_me_sqlite.py ....                                      [ 69%]
tests/test_security.py ......                                            [ 75%]
tests/test_security_expanded.py .....                                    [ 80%]
tests/test_shared_memory.py ..                                           [ 82%]
tests/test_sqlite.py .....                                               [ 88%]
tests/test_store_factory.py ...                                          [ 91%]
tests/test_vault.py .....                                                [ 96%]
tests/test_vault_security.py ...                                         [100%]

======================= 94 passed, 41 warnings in 13.38s =======================

🛠️ How to Execute the Test Suite

# 1. Run all unit & integration tests locally (Light Mode with SQLite)
uv run pytest tests/ -v

# 2. Run with coverage report
uv run pytest tests/ --cov=gomaa --cov-report=term-missing

# 3. Run full test suite including live PostgreSQL + pgvector tests
MEMORY_DB_DSN="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}" uv run pytest tests/ -v

🛡️ Test Procedure & Hermetic Isolation Principles

1. Hermetic Test Isolation: All tests utilize pytest's temporary filesystem fixtures (tmp_path) to generate ephemeral Obsidian vaults and SQLite databases, ensuring zero state pollution between runs.
2. Transaction Rollback Safety: Database operations and file writes are atomic. If an upsert or vector calculation fails, sibling temporary files (.note.pid.tmp) are cleaned up immediately.
3. Prompt Injection & Red-Teaming Tests: Automated test suites in tests/test_injection_defense.py and tests/test_security.py continuously verify that LLM control tokens, DAN mode overrides, path traversal attempts, and credential leaks are neutralized.

📄 License

Apache-2.0 License. Built for the open autonomous agent ecosystem. See LICENSE for full details.