Mnemosyne
This MCP server gives AI agents a persistent, vault-backed cognitive memory: it stores, searches, consolidates, and injects memories with wing/room scoping and a shared cross-agent fleet layer.
Store memories (
memory_remember): save private markdown notes with embeddings, tags, salience,pinneddecay immunity, and wing/room scope.Share fleet knowledge (
memory_publish_shared): publish sanitized, credential-free findings/policies to the cross-agent shared store.Search memory (
memory_recall): query byhybrid,semantic,keyword, orgraphmode, with optional wing/room scope andinclude_shared.Ingest conversations (
memory_ingest_session): store a full transcript verbatim, chunked along turn boundaries.Review activity (
memory_timeline): see recent memory operations in chronological order.Audit note versions (
memory_history): inspect past edits/snapshots of a specific note.Schedule reminders (
memory_remind_me): set future or recurring (daily/weekly/monthly) prospective reminders.Assemble prompt context (
memory_assemble_context): pack high-salience memories into a token-budgeted XML block for direct LLM context injection.Check system health (
memory_audit): get stats, health, active wings, and version info.
Note: the schema exposes 9 tools, fewer than the 13 claimed in the README, and its recall/assemble mode enums omit README-only modes like associative_ppr, procedural, and episodic.
Integrates with Cloudflare Workers for building platform connectors and consent mechanisms in the prototype.
Integrates with NEAR blockchain for consent NFTs, enabling data ownership and permission tracking.
Stores memories as Markdown files in an Obsidian vault, allowing direct editing and local ownership.
Uses Ollama for local embeddings, enabling memory indexing with locally hosted models.
Uses PostgreSQL with pgvector for vector similarity search and metadata storage.
Uses SQLite as a lightweight embedded database for memory storage, ideal for development and personal use.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mnemosyneremember the API rate limit decision: 100 req/min"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gomaa π§
Production-grade, local-first hierarchical & neuro-inspired cognitive memory engine for autonomous AI agents (v4.0.0 β "Gomaa Neo").
Gomaa equips AI agents (Hermes, OpenClaw, Claude Desktop, Cursor, Windsurf, CrewAI, LangChain) with permanent, human-like and transhuman long-term memory. It unites human-readable Obsidian Markdown Vaults with high-speed PostgreSQL + pgvector (HNSW) or zero-config SQLite WAL, powering a 4-Quadrant Cognitive Architecture (Episodic, Semantic, Procedural, Working Memory), HippoRAG 2 Personalized PageRank (PPR) associative retrieval, 3-Phase Biological Sleep Consolidation (SWS + REM + Synaptic Homeostasis), ACT-R Base-Level Activation, hybrid Reciprocal Rank Fusion (RRF) search, Ebbinghaus temporal decay, cross-agent fleet sharing, and asynchronous Google Drive cloud synchronization.
π‘ Why Gomaa?
Most AI memory systems suffer from three fundamental flaws:
Black-Box Vector Blobs: Memories disappear into opaque vector databases. Humans cannot audit, correct, or curate what the agent learned.
Context Pollution & Flat Storage: Raw chat logs, factual knowledge, and procedural skills are dumped into a single flat vector index without forgetting mechanisms or cognitive separation.
Multi-Hop Blindness & Domain Cross-Contamination: Standard vector similarity fails when connecting facts across multiple hops, while un-scoped stores leak context across domains.
Gomaa v4.0 ("Gomaa Neo") solves this:
π§ 4-Quadrant Cognitive Architecture: Explicit separation of Episodic (
episodic_eventsturn ledger), Semantic (notes+ weightedlinks), Procedural (procedural_playbookswith Bayesian Laplace utility), and Working Memory (working_memorybounded by Miller's Law $7 \pm 2$).πΈοΈ HippoRAG 2 Associative PPR Retrieval: Single-step multi-hop retrieval using Personalized PageRank ($K=20, \alpha=0.15$) over bi-directional weighted graph links, fused with dense vectors, BM25 FTS, and ACT-R base-level activation ($\ln(1 + \text{access_count})$).
π 3-Phase Biological Sleep Consolidation (
gomaa sleep): Slow-Wave Sleep (SWS) crystallizes high-surprise episodes into semantic notes and extracts procedural playbooks; REM sleep shares proven playbooks across the agent fleet and discovers latent tag-bridge links; Synaptic Homeostasis resolves epistemic conflicts via an Assumption-based Truth Maintenance System (ATMS).π Human-in-the-Loop Auditability: Every semantic memory is a human-readable Markdown note in your Obsidian vault with
[[Wiki Links]]and YAML frontmatter.β³ Ebbinghaus Temporal Decay & Pinned Immunity: Inactive memories fade exponentially ($Salience \times 0.95^{\Delta t}$) while
#pinnedmemories stay permanent.ποΈ Physical Wing & Room Scoping: A 2-level taxonomy (
wing= domain/project,room= channel/topic) isolates context strictly.π Cross-Agent Fleet Memory: Multi-agent swarms share sanitized global policies and high-utility playbooks through
shared_dbwhile keeping private databases isolated.
Related MCP server: Synapto
π Quick Start & Installation
Choose between two straightforward deployment modes depending on your setup:
β‘ Option 1: Lightweight Standalone Mode (Zero-Config SQLite WAL)
Best for: Standalone agents, individual developer workstations (Claude Desktop, Cursor IDE, Windsurf, CLI tools). Zero external database installation required (<1MB package size).
A. 1-Line Online Installer
Run this single command in your terminal to install Gomaa, initialize your local Obsidian vault, and generate ready-to-copy MCP configurations:
curl -fsSL https://raw.githubusercontent.com/M4F-S/gomaa/main/install.sh | bashB. Manual Pip Install
# 1. Install lightweight core
pip install gomaa
# 2. Initialize local memory vault (~/.gomaa/vault)
gomaa init
# 3. Launch interactive web knowledge graph dashboard
gomaa dashboardC. Connect to Claude Desktop or Cursor IDE
Add this MCP block to your agent configuration file:
1. Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"gomaa": {
"command": "python3",
"args": ["-m", "gomaa", "server"],
"env": {
"MEMORY_VAULT_PATH": "~/.gomaa/vault",
"MEMORY_DEFAULT_WING": "general"
}
}
}
}2. Cursor IDE (.cursor/mcp.json)
{
"mcpServers": {
"gomaa": {
"command": "python3",
"args": ["-m", "gomaa", "server"],
"env": {
"MEMORY_VAULT_PATH": "~/.gomaa/vault",
"MEMORY_DEFAULT_WING": "codebase"
}
}
}
}π Option 2: Full Production Fleet Deployment (PostgreSQL + pgvector)
Best for: Multi-agent swarms (Hermes, OpenClaw, CrewAI fleets), production servers, and large-scale vector search requiring HNSW indexing, cross-agent shared_db, and centralized embedding services.
A. Docker Compose (1-Command Full Stack)
Spin up PostgreSQL 16 with pgvector, pre-configured memory databases, and the Gomaa MCP server in 5 seconds:
git clone https://github.com/M4F-S/gomaa.git
cd gomaa
docker compose up -dB. Python Package Installation (Full Features)
# 1. Install Gomaa with all production extras (pgvector, fastembed, server, gdrive)
pip install "gomaa[all]"
# 2. Configure your PostgreSQL connection strings
export MEMORY_DB_DSN="postgresql://gomaa:gomaa_secure_password@localhost:15432/gomaa"
export MEMORY_SHARED_DSN="postgresql://gomaa:gomaa_secure_password@localhost:15432/shared_db"
export MEMORY_VAULT_PATH="~/.gomaa/vault"
# 3. Launch the visual Web Knowledge Graph Dashboard
gomaa dashboard --port 8765π Table of Contents
β‘ Complete Feature Matrix
Feature | Description | Benefit |
π€ MCP Native (v2024-11-05) | Standardized stdio JSON-RPC protocol server (13 tools) | Seamless drop-in for Claude, Cursor, Windsurf, Hermes, OpenClaw |
π§ 4-Quadrant Cognitive Store | Dedicated schemas for Episodic, Semantic, Procedural, and Working Memory | Prevents chat logs, factual knowledge, and tool skills from polluting each other |
πΈοΈ HippoRAG 2 Associative PPR | Personalized PageRank ($K=20, \alpha=0.15$) over bi-directional weighted edges | Solves multi-hop associative queries in a single sub-millisecond retrieval step |
π 3-Phase Sleep Consolidation | SWS crystallization + REM swarm playbook synthesis & link discovery + ATMS homeostasis | Automatically distills raw episodes into semantic notes and reusable procedural skills |
π High-Recall HNSW Vector Search |
| Sub-millisecond vector recall without clustering retraining |
βοΈ Hybrid RRF + ACT-R Ranking | Fuses Dense (1.0) + FTS (0.8) + Graph (0.6) + HippoRAG PPR (0.9) + Salience/ACT-R | Captures exact technical keywords, multi-hop graph bridges & frequently accessed facts |
ποΈ Wing & Room Scoping | 2-level taxonomy ( | Eliminates context window bloating & cross-domain hallucination |
π Cross-Agent Shared Memory | Central | Collective fleet intelligence without compromising private databases |
βοΈ Cloud & Local Vault Backup | Async Google Drive sync, local cloud drive sync (iCloud, Dropbox) & one-click archives | Sub-millisecond local speed + automated cloud backup & conflict branching |
β³ Ebbinghaus Temporal Decay | Exponential decay $Salience_t = Salience_0 \times (0.95)^{\Delta t}$ with 90-day auto-archive | Auto-prunes transient noise while keeping active memories sharp |
π Pinned Memory Immunity | Permanent immunity to decay via | Guarantees foundational instructions and core rules never fade |
π Obsidian Zettelkasten | Writes human-readable Markdown notes with YAML frontmatter & | Direct visual inspection, editing, and graph visualization in Obsidian |
π Turn-Aware Ingestor | 1,500-char sliding-window chunking with 200-char overlap along turn boundaries | Preserves entire conversation history without breaking code blocks |
π‘οΈ Prompt Injection Armor | Neutralizes control tokens (`< | im_start |
π¨ Native Aurora Dashboard | Zero-dependency embedded web knowledge graph ( | Real-time visual memory graph, cognitive distribution charts & live query sandbox |
π¦ Token-Budgeted Assembler | Packs top-salience memories into exact LLM prompt budgets with XML escaping | Direct drop-in context injection for LLM system prompts without overflow |
π Framework Adapters | Native integrations for LangChain, LangGraph, and CrewAI (including Procedural recall) | Drop-in multi-agent swarm memory with zero boilerplate |
π Zero-Config SQLite Light Mode | Automatic fallback to local SQLite WAL when PostgreSQL is offline | 5-second setup with 100% feature parity for standalone developer workstations |
ποΈ System Architecture
flowchart TD
subgraph Clients["π€ AI Agents & LLM Clients"]
Claude["Claude Desktop / Cursor"]
Hermes["Autonomous Multi-Agent Swarms"]
Swarm["CrewAI / LangGraph Swarms"]
end
subgraph Core["π§ Gomaa Core Engine (v4.0.0 - Gomaa Neo)"]
direction TB
MCP["MCP JSON-RPC Server\n(13 Tools Β· Stdio)"]
Security["Admission & Security Guard\n(Credential Regex Β· Control Token Sanitizer)"]
RRF["Hybrid RRF + HippoRAG 2 PPR Ranker\nDense(1.0) + PPR(0.9) + FTS(0.8) + Graph(0.6) + ACT-R"]
Sleep["3-Phase Biological Sleep Engine\n(SWS Crystallization Β· REM Playbooks Β· ATMS Homeostasis)"]
Assembler["Token-Budgeted Context Assembler\n(Structured XML Prompt Enclosure)"]
end
subgraph Quadrants["ποΈ 4-Quadrant Cognitive Topology (PostgreSQL 16 pgvector & SQLite WAL)"]
Episodic[("β‘ Episodic Ledger\nepisodic_events")]
Semantic[("π Semantic Graph\nnotes + weighted links")]
Procedural[("π οΈ Procedural Store\nprocedural_playbooks")]
Working[("π― Working Memory\nworking_memory (7Β±2)")]
Vault["π Obsidian Markdown Vault\nYAML Frontmatter Β· [[Wikilinks]]"]
end
subgraph Cloud["βοΈ Remote Sync (Optional)"]
GDrive["Google Drive Cloud Sync\n(MD5 Diffing Β· Conflict Branching)"]
end
Clients -->|MCP stdio / Python SDK| MCP
MCP --> Security
Security --> RRF
Security --> Sleep
RRF <--> Episodic
RRF <--> Semantic
RRF <--> Procedural
RRF <--> Working
Semantic <--> Vault
Sleep --> Episodic
Sleep --> Semantic
Sleep --> Procedural
Assembler --> Clients
Vault <-->|Async Daemon / Cron| GDriveπ§ Deep Dive into Key Capabilities
1. 4-Quadrant Cognitive Architecture (v4.0)
Inspired by cognitive neuroscience (Tulving, Squire, Anderson's ACT-R), Gomaa v4.0 separates agent memory into four specialized stores across both SQLite and PostgreSQL:
Episodic Memory (
episodic_events): Autonoetic, append-only turn ledger recording raw agent stimuli, tool invocations, outcomes (success,failure,partial), and asurprise_factor($[0.0, 1.0]$).Semantic Memory (
notes+links): Noetic, decontextualized factual knowledge stored simultaneously in the Obsidian vault and database with typed, weighted edges (relation_type,edge_weight),access_count, and ATMS provenance (status,superseded_by).Procedural Memory (
procedural_playbooks): Executable skill schemas storingpreconditions,tool_sequence, anderror_recoverypolicies ranked by Bayesian Laplace-smoothed success rate: $$U_{\text{Bayesian}} = \frac{\text{success_count} + 1}{\text{invocation_count} + 2}$$Working Memory (
working_memory): Session-scoped scratchpad trackingactive_goal,subtask_stack,hypotheses, and anattention_windowstrictly bounded by Miller's Law ($7 \pm 2 \Rightarrow \text{max } 9$ items).
2. HippoRAG 2 Personalized PageRank (PPR) & Hybrid RRF Search
Standard vector search fails on exact technical strings (e.g. CVE-2024-38077) and multi-hop associative bridges. Gomaa v4.0 implements HippoRAG 2 Personalized PageRank (associative_ppr) alongside hybrid Reciprocal Rank Fusion:
Personalized PageRank (
gomaa/hipporag.py): Extracts top anchor nodes via dense cosine similarity to build a sparse personalization reset distribution $p$, then runs 20 power iterations ($\alpha=0.15$) over bi-directional forward and backlink graph edges: $$\pi^{(k+1)} = \alpha \cdot p + (1 - \alpha) \cdot M^{\top} \pi^{(k)}$$5-Way Hybrid RRF + ACT-R Fusion: $$\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) + 0.05 \cdot \ln(1 + \text{access_count}(d))$$ Combining Dense Vector ($1.0$), HippoRAG PPR ($0.9$), Full-Text Search ($0.8$), 2-Hop Graph Walk ($0.6$), Salience ($0.2$), and ACT-R Base-Level Activation.
3. 3-Phase Biological Sleep Consolidation (gomaa sleep)
Instead of simple decay, Gomaa v4.0 implements a 3-phase offline consolidation cycle (ConsolidationEngine.run()):
Phase 1 β Slow-Wave Sleep (SWS β Episodic-to-Semantic Crystallization): Scans unconsolidated
episodic_events. High-surprise episodes ($\text{surprise_factor} \ge 0.5$ or failure recovery) are crystallized into permanent Semantic Markdown notes in the Obsidian vault and database, while multi-step successful tool trajectories ($\ge 2$ tool calls) are extracted intoprocedural_playbooks.Phase 2 β REM Sleep (Associative Synthesis & Swarm Skill Sharing): Promotes high-utility procedural playbooks ($\text{bayesian_success_rate} \ge 0.60$, screened by
AdmissionControl) to the cross-agentshared_dbfleet store, and discovers latentrem_associativelinks between unlinked semantic notes sharing domain tags.Phase 3 β Synaptic Homeostasis & ATMS Truth Maintenance: Resolves pending contradictions in
epistemic_conflictsby marking superseded notesstatus = 'deprecated'withsuperseded_byprovenance pointers, then applies geometric Ebbinghaus step decay ($S_{t+1} = S_t \times d$).
4. 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.
5. Cross-Agent Shared Memory Layer (shared_db)
In autonomous multi-agent environments, agents maintain isolated private databases (e.g. agent_orchestrator, agent_researcher, agent_executor, etc.) to prevent state corruption. However, collective intelligence requires sharing global policies and verified facts.
Publishing: Using
memory_publish_shared, vetted notes are published toshared_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_recallqueries both the private store andshared_db. If the shared database is temporarily unreachable, it degrades gracefully without interrupting the agent.
6. Ebbinghaus Temporal Decay, ACT-R Activation & Pinned Immunity
Memories naturally lose relevance over time while frequently recalled memories grow stronger:
ACT-R Dynamic Access Tracking: Every high-confidence semantic or keyword recall increments
access_countand updateslast_accessed_at, boosting the note's base-level activation $\ln(1 + \text{access_count})$.Nightly Auto-Archiving: Consolidation automatically transitions notes below the archive threshold and unaccessed for $>90\text{ days}$ to
status = 'archived'.Pinned Immunity: System rules, core policies, or notes marked with
pinned=Trueor tagged#pinnedreceive permanent immunity from temporal decay ($\text{Salience} = 1.0$).
7. 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, androom.Bi-Directional Knowledge Graph: Target notes mentioned as
[[Target Note]]are automatically parsed into bi-directional relationships in PostgreSQL & SQLite, enabling 2-hop traversal and HippoRAG PPR propagation across both forward links and backlinks.Live Inspection: Open Obsidian on your desktop or mobile device and explore your agent fleet's collective memory in Obsidian's interactive Graph View.
8. 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.
9. Cloud & Local Vault Backup (Google Drive, Local Sync, One-Click Archives)
Ensure your agent vaults and memory stores are permanently preserved, version-controlled, and synchronized across cloud providers or local filesystems:
A. Direct Google Drive Asynchronous Synchronization (gomaa sync-gdrive)
Local-First Zero Latency: Agents read and write directly to the local vault at SSD speeds (<1ms). Background synchronization interacts with the Google Drive v3 API asynchronously without blocking agent execution.
Cryptographic MD5 Verification: Automatically verifies checksums to prevent redundant uploads or downloads.
Conflict Branch Preservation: If a note is updated on Google Drive and modified locally simultaneously, Gomaa automatically preserves the local note as
NoteName.conflict-YYYYMMDD-HHMMSS.mdbefore updating, guaranteeing zero data loss.Authentication Options:
Service Account File: Pass
--credentials /path/to/service-account.jsonor setexport GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json".Service Account JSON String: Set
export GDRIVE_SERVICE_ACCOUNT_JSON='{"type": "service_account", ...}'.User OAuth2 Token: Set
export GDRIVE_TOKEN_JSON='{"token": "...", "refresh_token": "..."}'.
Execution Modes:
# Single one-off sync pass gomaa sync-gdrive --folder "Agent-Vault" --credentials service-account.json # Continuous background synchronization daemon (e.g. sync every 5 minutes) gomaa sync-gdrive --daemon --interval 300
B. Local Cloud Drive & Desktop Folder Sync (gomaa sync-folder)
If you use Google Drive for Desktop, Dropbox, iCloud Drive, OneDrive, or an external backup volume, Gomaa can synchronize directly with the synced desktop folder without requiring cloud API keys or developer console setup:
# Sync with Google Drive for Desktop
gomaa sync-folder "~/Google Drive/My Drive/GomaaVault"
# Sync with Dropbox or iCloud
gomaa sync-folder "~/Dropbox/GomaaVault"
gomaa sync-folder "~/Library/Mobile Documents/com~apple~CloudDocs/GomaaVault"C. Universal One-Click Backup & Restore (gomaa backup / gomaa restore)
Create atomic, timestamped compressed archives containing your entire Obsidian vault (all markdown notes, wikilinks, attachments) and the SQLite database:
# Create timestamped tar.gz or zip backup archive
gomaa backup --dest ./backups
gomaa backup --dest ~/Google\ Drive/My\ Drive/Backups --format zip
# Restore vault and database from backup archive
gomaa restore ./backups/gomaa-backup-20261014-120000.tar.gz --dest-vault ~/.gomaa/vault10. Flexible Embedding Backends (FastEmbed / Microservice / Local)
Gomaa adapts to any deployment resource budget:
FastEmbed ONNX Runtime (Recommended for Standalone Nodes): Uses ONNX Runtime C++ execution (~30MB RAM). Zero PyTorch overhead.
Centralized Microservice (
gomaa.embed_service): Hosts sentence-transformers in a single dedicated container serving multiple agent containers over HTTP (MEMORY_EMBED_URL).Local SentenceTransformers: Standalone PyTorch execution (
all-MiniLM-L6-v2, 384-dimensional).Deterministic Hash Fallback: Zero-RAM mathematical vector hash for ultra-constrained environments.
11. Defense-in-Depth Security & Data Integrity
Path Traversal Immunity: Dual-resolved canonical path checks (
is_relative_to) ensure file operations cannot escape the vault root.Thread-Safe Atomic Writes: Files are written to unique sibling temporary files (
.{name}.{pid}.{uuid}.tmp) and renamed atomically, preventing thread collisions with automatic fallback forEXDEVcross-device volume mounts.DB-Failure Safe Rollback: If a database upsert fails, existing notes are restored from content backups, preventing data corruption.
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 (13 Tools)
All 13 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, semantic, keyword, 2-hop graph, HippoRAG associative_ppr, procedural playbooks, or episodic turns.
{
"query": "HNSW index configuration parameters",
"mode": "associative_ppr",
"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 agent connection pools are refreshed with new credentials.",
"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_ingest_event
Log a turn-level experiential episode into the biological episodic ledger (episodic_events) with a surprise rating and outcome status.
{
"session_id": "sess-2026-01",
"event_type": "tool_call",
"stimulus": "nmap -p 8080 10.0.0.5",
"response": "Port 8080 open (Apache Tomcat)",
"tool_name": "nmap_scan",
"tool_args": {"port": 8080, "target": "10.0.0.5"},
"surprise_factor": 0.85,
"outcome_status": "success"
}10. memory_save_playbook
Store or update a reusable procedural skill playbook (procedural_playbooks) with preconditions, tool sequences, error recovery, and Bayesian Laplace-smoothed utility tracking.
{
"skill_name": "harden_ssh_daemon",
"domain": "devops",
"description": "Disable password auth and root password login in sshd_config",
"preconditions": ["root_access", "ssh_key_installed"],
"tool_sequence": [
{"tool": "edit_config", "args": {"file": "/etc/ssh/sshd_config"}},
{"tool": "systemctl_reload", "args": {"service": "ssh"}}
],
"error_recovery": {"syntax_error": "sshd -t && restore backup"}
}11. memory_sleep
Trigger the 3-phase biological sleep consolidation engine (Slow-Wave Sleep crystallization + REM swarm playbook synthesis & latent link discovery + ATMS synaptic homeostasis).
{
"decay_factor": 0.95,
"archive_threshold": 0.10
}12. memory_working_buffer
Manage the Miller's Law ($7 \pm 2$) bounded working memory scratchpad (get, update, clear) for active session goals, subtask stacks, hypotheses, and attention windows.
{
"action": "update",
"session_id": "sess-2026-01",
"agent_role": "lead_researcher",
"active_goal": "Verify zero-downtime migration",
"subtask_stack": ["Check replica lag", "Switch PgBouncer pool"],
"hypotheses": ["Replica lag < 10ms under load"],
"attention_window": [{"note": "PostgreSQL HNSW Tuning", "salience": 0.9}]
}13. memory_audit
Get real-time memory health metrics, store backend status, request counts, and active wings.
{}π Multi-Agent Fleet Production Architecture
In enterprise multi-agent production deployments, Gomaa provides strict database isolation per agent container or worker process on an internal Docker network, paired with a central shared_db for collective intelligence and vetted fleet-wide policies:
βββββββββββββββββββββββββββββββββββββββββββ
β Production Cloud / Cluster β
ββββββββββββββββββββββ¬βββββββββββββββββββββ
β
βββββββββββββββββββββ¬βββββββββββββββββββΌββββββββββββββββββββ¬βββββββββββββββββββ
βΌ βΌ βΌ βΌ βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βagent-orchestratorββ agent-research ββ agent-executor ββ agent-security ββ agent-operations β
β (Coordinator) ββ (Data/Search) ββ (Code/Tasks) ββ (Compliance) ββ (DevOps) β
β Database: ββ Database: ββ Database: ββ Database: ββ Database: β
β orchestrator_db ββ research_db ββ executor_db ββ security_db ββ operations_db β
ββββββββββ¬ββββββββββββββββββββ¬ββββββββββββββββββββ¬ββββββββββββββββββββ¬ββββββββββββββββββββ¬ββββββββββ
β β β β β
βββββββββββββββββββββ΄βββββββββββββββββββΌββββββββββββββββββββ΄βββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββ
β PostgreSQL 16 + pgvector (HNSW) β
β - Private Isolated Agent DBs β
β - Shared Collective DB β
βββββββββββββββββββββββββββββββββββββArchitectural Guarantees:
Zero Domain Bleed: Each agent maintains its own private
pgvectororSQLitedatabase. Queries generated byagent-securitywill never recall unrelated working context fromagent-operations.Sanitized Fleet Knowledge Sharing (
shared_db): High-utility procedural playbooks and verified domain policies can be published globally usingmemory_publish_shared. Content passes automated regex credential screening (neutralizing API keys, passwords, and private tokens) before reaching the shared layer.Resilient Fail-Soft Federation: When an agent invokes
memory_recall(include_shared=True), Gomaa queries both the agent's private store and the fleetshared_db. If the shared database is temporarily offline or undergoing maintenance, Gomaa gracefully returns private memory results without throwing an exception or interrupting agent execution.
π€ Agent Framework Integration Recipes
1. Hermes Agent Swarm (~/.hermes/config.yaml)
mcp_servers:
obsidian_memory:
command: python3
args: ["-m", "gomaa", "server"]
env:
MEMORY_AGENT_NAME: "agent-orchestrator"
MEMORY_DB_DSN: "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/orchestrator_db"
MEMORY_SHARED_DSN: "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/shared_db"
MEMORY_VAULT_PATH: "~/.hermes/vault"2. OpenClaw (openclaw-config.yaml)
plugins:
mcp_servers:
gomaa:
command: "python3"
args: ["-m", "gomaa", "server"]
env:
MEMORY_VAULT_PATH: "~/.openclaw/vault"
MEMORY_DEFAULT_WING: "openclaw"3. 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.")4. 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"
)5. Python SDK & Autonomous Agent Scripts
from gomaa import UnifiedMemorySystem
mem = UnifiedMemorySystem(
vault_path="~/.agent/vault",
dsn="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/agent_db",
shared_dsn="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@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 / associative_ppr / procedural / episodic)
gomaa recall "JWT authentication" --mode associative_ppr --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 3-phase biological sleep consolidation (SWS + REM + Homeostasis)
gomaa sleep --decay-rate 0.95 --archive-threshold 0.10
# 9. Trigger Ebbinghaus decay & link reconciliation
gomaa consolidate --decay-rate 0.95 --archive-threshold 0.05
# 10. Check system statistics & health
gomaa stats
# 11. Create a timestamped compressed backup archive (vault + database)
gomaa backup --dest ./backups --format tar.gz
# 12. Restore vault and database from backup archive
gomaa restore ./backups/gomaa-backup-20261014-120000.tar.gz --dest-vault ~/.gomaa/vault
# 13. Sync vault with local cloud folder (Google Drive for Desktop, Dropbox, iCloud)
gomaa sync-folder "~/Google Drive/My Drive/GomaaVault"
# 14. Synchronize with Google Drive API (One-off pass or daemon mode)
gomaa sync-gdrive --folder "My-Agent-Vault" --credentials service-account.json
gomaa sync-gdrive --daemon --interval 300
# 15. Run standalone Centralized Embedding Microservice
gomaa embed-service --host 0.0.0.0 --port 8000 --model all-MiniLM-L6-v2βοΈ Environment Variables Reference
Variable | Default | Description |
|
| Filesystem path to the local Obsidian Markdown vault directory |
| (none) | PostgreSQL DSN (e.g. |
| (none) | PostgreSQL DSN for the optional cross-agent shared fleet database |
|
| Identifier for the origin agent in multi-agent fleet deployments |
| (none) | URL of remote centralized embedding microservice (e.g. |
|
| Set |
| (none) | File path to Google Cloud Service Account JSON for Google Drive synchronization |
| (none) | Stringified JSON content of Google Cloud Service Account credentials |
| (none) | Stringified JSON content of authorized Google OAuth2 user token |
|
| Disables HuggingFace tokenizer forks to preserve stdio JSON-RPC stream integrity |
|
| Disables progress bars in stdio to keep MCP streams pristine |
|
| Set |
|
| Set |
π§ͺ 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:
Operation | Implementation | Mean Latency | P95 Latency | Throughput |
Cold Engine Init | SQLite WAL + Obsidian Vault | 6.28 ms | 6.50 ms | ~160 init/s |
Neural Ingest | FastEmbed ONNX + SQLite + Markdown File IO | 13.50 ms | 21.47 ms | ~75 notes/s |
Neural Recall | Query Embedding + Dot Product + Keyword RRF | 13.71 ms | 14.79 ms | ~73 queries/s |
HippoRAG 2 PPR | 20-Step Power Iteration ($K=20, \alpha=0.15$) | 1.42 ms | 1.85 ms | ~700 walks/s |
Keyword FTS Search | SQLite FTS5 / PostgreSQL GIN | 0.99 ms | 1.24 ms | ~1,010 queries/s |
Graph Traversal | Recursive CTE / In-Memory Wikilink Walk | 0.83 ms | 0.97 ms | ~1,200 walks/s |
Context Assembler | Top-K Recall + Token Budgeting + XML Packing | 6.12 ms | 6.45 ms | ~163 assemblies/s |
π¬ Test Suite Coverage (126 / 126 Passed Β· 100%)
Gomaa v4.0 maintains a comprehensive automated test suite spanning 33 test modules (including LoCoMo, LongMemEval, and HotpotQA multi-hop cognitive benchmark harnesses):
collected 126 items
tests/benchmarks/test_memory_benchmarks.py ... [ 2%]
tests/test_adapters.py .. [ 3%]
tests/test_assemble_context.py ... [ 6%]
tests/test_backup.py .... [ 9%]
tests/test_chunking.py . [ 10%]
tests/test_cli_init.py .. [ 11%]
tests/test_compat.py .... [ 15%]
tests/test_consolidation.py .. [ 16%]
tests/test_dashboard.py ...... [ 21%]
tests/test_dream_consolidation.py .... [ 24%]
tests/test_embedder.py ... [ 26%]
tests/test_embedder_offline.py . [ 27%]
tests/test_embedder_v32.py .. [ 29%]
tests/test_fts_websearch.py . [ 30%]
tests/test_gdrive_safe_path.py ..... [ 34%]
tests/test_gdrive_sync.py ..... [ 38%]
tests/test_graph_cycles.py . [ 38%]
tests/test_hipporag.py ... [ 41%]
tests/test_injection_defense.py ... [ 43%]
tests/test_integration.py ... [ 46%]
tests/test_mcp.py .. [ 47%]
tests/test_mcp_edge_cases.py .... [ 50%]
tests/test_mcp_server.py ................... [ 65%]
tests/test_quadrant_stores.py ....... [ 71%]
tests/test_reconcile_links.py . [ 72%]
tests/test_remind_me_sqlite.py .... [ 75%]
tests/test_security.py ...... [ 80%]
tests/test_security_expanded.py ..... [ 84%]
tests/test_shared_memory.py .. [ 85%]
tests/test_sqlite.py ..... [ 89%]
tests/test_store_factory.py ... [ 92%]
tests/test_vault.py ..... [ 96%]
tests/test_vault_security.py ..... [100%]
======================= 126 passed in 8.12s =======================π οΈ 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
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.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.Prompt Injection & Red-Teaming Tests: Automated test suites in
tests/test_injection_defense.pyandtests/test_security.pycontinuously 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.
Available Tools
9 toolsmemory_assemble_contextA
Retrieve and format high-salience memories into a strict token-budgeted XML prompt block ready for direct agent context injection.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | hybrid | |
| query | Yes | Search query to retrieve context for | |
| scope | No | Optional wing/room filter scope | |
| max_tokens | No | Maximum token budget for the assembled context | |
| include_shared | No | Whether to include shared fleet knowledge |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool retrieves rather than mutates, filters for 'high-salience', enforces a 'strict token-budget', and formats into XML. This is useful, though it doesn't explain how salience is determined or how failures/token-truncation are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense, front-loaded sentence with no filler. It names the primary action, the input type, the processing behavior, and the output format in an efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key output (XML prompt block) but leaves important gaps for a tool with five parameters and no annotations: the meaning of each `mode`, how `scope` is applied, the effect of `include_shared`, and expected behavior when the token budget is exceeded. The schema fills some gaps, but the description alone isn't fully complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameter meanings. The description adds some context around token budgeting and salience, but it doesn't elaborate on the `mode` enum, `scope` object, or `include_shared` flag beyond what the schema fields already say. This is adequate but not additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve and format') and resource ('high-salience memories'), and specifies the unique output format: 'strict token-budgeted XML prompt block ready for direct agent context injection.' It doesn't explicitly name sibling alternatives, but the XML formatting and context-injection purpose distinguish it from tools like memory_recall or memory_timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: assemble memory context for direct agent injection. It does not name when to use this over alternatives, nor provide any when-not-to-use guidance. The phrase 'ready for direct agent context injection' gives some context, but an agent would need to infer the comparison with memory_recall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_auditA
Get memory system statistics, health check, active wings, and version info
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. The verb 'Get' strongly implies a read-only operation, and the listed outputs suggest no mutation. However, it does not explicitly state that no state changes occur, whether permissions are required, or whether the health check performs any active diagnostics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence with no filler. The verb is front-loaded and each listed item contributes meaning. Every word earns its place, and the structure is easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and no output schema, the description needs to convey what the tool returns. It does so by listing four output categories: statistics, health check, active wings, and version info. This is adequate for simple invocation, though the term 'active wings' is domain-specific and not expanded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter documentation. Per the baseline for a zero-parameter tool, the description does not need to compensate for parameter gaps; it simply describes the operation's outputs, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Get' and names distinct resources: memory system statistics, health check, active wings, and version info. This makes the tool's focus clear and differentiates it from content-oriented siblings like memory_recall or memory_history, though it does not explicitly contrast itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose memory_audit over sibling tools. While the system-level subject matter implies a diagnostic use case, the description does not explicitly state when to run an audit versus when to use memory_history, memory_timeline, or memory_assemble_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_historyB
View version history of a specific memory note (previous edits).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| title | Yes | The title of the note to check history for |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only indicates a read-style operation ('View') and says nothing about the shape of the returned history, ordering, pagination, or how 'previous edits' are represented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is easy to parse and economical, though it may be too terse to convey all necessary behavioral and parameter guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool, the description names the resource and indicates the action, and the required title parameter is sufficient to invoke it. However, with no output schema and no annotations, the lack of return-format and limit semantics leaves clear gaps for an agent trying to use the results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The title parameter is already documented in the schema, but the limit parameter has no description and the tool description adds no meaning for it. With 50% schema coverage, the description needed to compensate for the undocumented parameter and did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('View') and a precise resource ('version history of a specific memory note'), with the clarifying parenthetical 'previous edits'. It is immediately clear what the tool does, but it does not explicitly contrast with sibling tools such as memory_timeline or memory_audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: checking the previous edits of one specific note. It gives enough context for when an agent should invoke it, though it provides no explicit exclusions or alternative routing to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_ingest_sessionA
Ingest a full conversation transcript verbatim into memory, split along conversational turn boundaries.
| Name | Required | Description | Default |
|---|---|---|---|
| room | No | sessions | |
| wing | No | general | |
| transcript | Yes | The full conversation text to ingest |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It usefully disloses that content is stored verbatim and split by turn boundaries, but it does not explain side effects, storage semantics, deduplication, limits, or whether repeated ingestion creates duplicates. These would be valuable for a memory-mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no filler, and the most decision-relevant information is front-loaded. The phrase about splitting along turn boundaries is efficiently included without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple ingestion tool, the core invocation path is clear: provide the full transcript. However, no output schema or annotations exist, and the optional room/wing parameters are unexplained, so an agent would need to infer their purpose from names or defaults. This leaves some contextual ambiguity around storage targeting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, with only 'transcript' having a schema description. The description adds meaning to the requied parameter by specifying 'verbatim' and 'split along conversational turn boundaries', but it does not explain the optional 'room' and 'wing' parameters, which remain defined only by their names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Ingest'), the resource ('full conversation transcript'), the destination ('into memory'), and the precise behavior ('verbatim, split along conversational turn boundaries'). This distinguishes it from sibling tools like memory_remember or memory_recall, which likely handle individual memories rather than bulk ingestion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for full multi-turn conversation transcripts, which suggests a bulk ingest use case distinct from memory_remember or memory_recall. However, it does not explicitly state when not to use it or name alternative tools, leaving any routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_recallB
Search memory by semantic meaning, keywords, or graph. Retrieves from both private and shared stores.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| query | Yes | ||
| scope | No | Restrict search to a wing and/or room | |
| top_k | No | ||
| include_shared | No | Whether to include cross-agent shared fleet memory |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool retrieves from both private and shared stores and that search can be semantic, keyword-based, or graph-based. However, it does not mention return format, whether any filtering or ranking applies, or any access caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. The primary action and retrieval scope are front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, a nested scope object, no output schema, no annotations, and several related sibling tools, this description is too sparse. It leaves important invocation details such as mode defaults, query semantics, shared-memory handling, and result expectations unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description compensates poorly. It loosely maps to the mode enum with 'semantic meaning, keywords, or graph' and mentions shared/private stores, but it does not clarify the required query parameter, the meaning of hybrid mode, top_k behavior, or the nested scope object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Search memory' and lists search methods (semantic, keyword, graph). It is clear about what the tool does, though it does not explicitly differentiate itself from sibling tools like memory_timeline or memory_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching/recalling stored memories, but it gives no explicit guidance on when to prefer memory_recall over alternatives like memory_assemble_context, memory_timeline, or memory_remind_me. Usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_rememberA
Store a private memory note in the vault with semantic embedding, tags, and hierarchical wing/room scope.
| Name | Required | Description | Default |
|---|---|---|---|
| room | No | Topic within the wing (e.g. woocommerce, firewall, docker) | general |
| tags | No | Categorical tags | |
| wing | No | Project/domain grouping (e.g. ecommerce, security, devops) | general |
| title | Yes | Short, unique title for the memory | |
| pinned | No | Set true to make permanently immune to Ebbinghaus temporal decay | |
| content | Yes | The memory content in markdown | |
| salience | No | Importance score 0.0-1.0 (default 0.5) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and it does add useful behavioral context: 'private,' 'vault,' 'semantic embedding,' and hierarchy. It does not disclose behaviors such as duplicate-title handling, temporal decay, or return value, which leaves some opacity for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb, and every detailβprivacy, vault, embedding, tags, scopeβearns its place. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Schema plus description covers what to pass, but the absence of annotations and output schema, combined with seven sibling tools, leaves gaps: no routing guidance versus ingestion/sharing tools and no statement of what happens on success or when a title already exists. Complete enough for basic invocation but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter already has meaningful descriptions (e.g., room is 'Topic within the wing'; pinned explains Ebbinghaus decay). The description adds only the notion of hierarchy, not substantive parameter semantics, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Store') and a specific resource ('private memory note in the vault') while naming key processing details: semantic embedding, tags, and hierarchical wing/room scope. 'Private' distinguishes it from shared publication, and the write verb separates it from retrieval siblings like memory_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the store verb: use this when saving a private memory note. However, the description provides no explicit when-to-use or when-not-to-use guidance and names no alternatives, so an agent must infer the boundary against siblings like memory_ingest_session and memory_publish_shared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_remind_meB
Schedule a future reminder or recurring task
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| content | No | ||
| recurring | No | ||
| trigger_at | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the full burden of behavioral disclosure. It only states the basic scheduling action and omits important traits such as trigger_at format, how recurrence is applied, side effects when the reminder fires, and whether a memory entry is also created.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient, front-loaded sentence with no wasted words. However, its brevity comes at the cost of necessary parameter and behavior details, so it is concise but not fully appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, no annotations, schema description coverage of 0%, and no output schema, this description is too thin. An agent cannot confidently determine how to provide trigger_at or how recurring should behave, so the definition is materially incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it names no parameters directly. It only hints at 'future' and 'recurring', leaving title, content, trigger_at format, and the relationship between recurring and trigger_at undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Schedule') and identifies the resource ('future reminder or recurring task'). This clearly distinguishes it from retrospective siblings like memory_recall, memory_timeline, and memory_history, and from memory_remember which implies storage rather than scheduling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Schedule a future reminder or recurring task' implies the core use case, but no explicit guidance is given about when to choose this over alternatives. There are no prerequisites, no exclusions, and no mention of sibling tools that might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_timelineB
View recent memory operations (remember, recall, remind, consolidate) as a chronological timeline.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of behavioral disclosure. 'View' and 'chronological timeline' imply a read-only listing, which is helpful, but no details are given about ordering direction, result format, pagination, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the main action and resource. Every word contributes value, and it includes useful examples of the operation types shown.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only timeline with one optional parameter, the description is mostly adequate. However, the lack of sibling differentiation, no mention of the `limit` parameter, and no output format details leave clear gaps for an agent deciding how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter `limit` has zero schema description coverage and the tool description does not mention it at all. While the parameter is somewhat self-explanatory from its name and default value, the description adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('View') and a clear resource ('recent memory operations') with examples of operation types. It is sufficiently clear that this is a timeline of memory operations, though it does not explicitly distinguish itself from the similarly named sibling 'memory_history'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings like `memory_recall` or `memory_history`, nor does it mention any alternative conditions. Usage context is only implied by the word 'View'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
9 tool updates
v3.5.0- First observed
memory_assemble_context - First observed
memory_audit - First observed
memory_history - First observed
memory_ingest_session - First observed
memory_publish_shared - First observed
memory_recall - First observed
memory_remember - First observed
memory_remind_me - First observed
memory_timeline
TDQS
Scored across 9 tools
Most tools target distinct memory operations: storing, retrieving, scheduling, auditing, and publishing. Some overlap exists between memory_recall (search) and memory_assemble_context (curated retrieval), but their descriptions make the intended use clear.
All tool names follow a consistent memory_verb_noun pattern using snake_case (e.g., memory_ingest_session, memory_publish_shared). The one slight deviation is memory_remind_me, but it still fits the overall verb-first convention.
Nine tools cover the core memory management lifecycle without feeling bloated. The set is well-scoped for a memory server, with each tool serving a clear and necessary function.
The server covers storing, retrieving, scheduling, sharing, and diagnostics, but lacks explicit update or delete/forget tools. Memory_history implies prior edits exist, yet no edit tool is exposed, which is a notable gap for a memory management system.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent, portable memory for AI assistants β your private memory graph, from any MCP client.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
- memnodeOAuthdev.memnode
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceGives AI agents persistent memory with semantic search, automatic extraction, and memory decay, accessible via MCP protocol.5 npmMIT
- AlicenseNot gradedqualityAmaintenanceProvides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.21 PyPI5MIT
- AlicenseAqualityDmaintenanceProvides persistent memory with semantic search for MCP-based AI agents, enabling them to store and recall information across sessions using vector embeddings.41MIT
- AlicenseNot gradedqualityAmaintenanceProvides persistent, graph-based memory for AI agents using Neo4j and vector embeddings, enabling semantic recall across sessions via MCP.1Apache 2.0