pug-brain

PugBrain: Reflex-based Neural Memory

Reflex-based memory system for AI agents — retrieval through activation, not search.

PugBrain is a hybrid neural-vector memory system for long-term agent continuity. It combines graph relationships with vector embeddings for reflexive recall.

PugBrain stores experiences as interconnected neurons and recalls them through spreading activation, mimicking how the human brain works. Instead of searching a database, memories surface through associative recall — activating related concepts until the relevant memory emerges.

45 MCP tools · 14 memory types · 24 synapse types · Schema v26 · 3778+ tests · Cognitive reasoning layer

Why Not RAG / Vector Search?

Aspect	RAG / Vector Search	PugBrain
Model	Search engine	Human brain
LLM/Embedding	Required (embedding API calls)	Optional — core recall is pure algorithmic graph traversal
Query	"Find similar text"	"Recall through association"
Structure	Flat chunks + embeddings	Neural graph + synapses
Relationships	None (just similarity)	Explicit: CAUSED_BY, LEADS_TO, RESOLVED_BY, etc.
Temporal	Timestamp filter	Time as first-class neurons
Multi-hop	Multiple queries needed	Natural graph traversal
Lifecycle	Static	Decay, reinforcement, consolidation
API Cost	~$0.02/1K queries	$0.00 — fully offline (optional embeddings available)

Example: "Why did Tuesday's outage happen?"

• RAG: Returns "JWT caused outage" (missing why we used JWT)
• PugBrain: Traces outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice → full causal chain

---

Installation

pip install pug-brain

Setup

Claude Code (Plugin)

/plugin marketplace add tannht/pug-brain
/plugin install pug-brain@pug-brain-marketplace

Cursor / Windsurf / Other MCP Clients

pip install pug-brain

Add to your editor's MCP config:

{
  "mcpServers": {
    "pugbrain": {
      "command": "pug-mcp"
    }
  }
}

Auto-initializes on first use — no pugbrain init needed.

OpenClaw

pip install pug-brain && npm install -g pugbrain

{ "plugins": { "slots": { "memory": "pugbrain" } } }

See the full setup guide.

Installation Options

pip install pug-brain[server]           # FastAPI server + dashboard
pip install pug-brain[extract]          # PDF/DOCX/PPTX/HTML/XLSX/CSV extraction
pip install pug-brain[embeddings]       # Local embedding (cross-language recall)
pip install pug-brain[embeddings-openai] # OpenAI embeddings
pip install pug-brain[embeddings-gemini] # Google Gemini embeddings
pip install pug-brain[nlp-vi]           # Vietnamese NLP
pip install pug-brain[neo4j]            # Neo4j backend
pip install pug-brain[falkordb]         # FalkorDB backend
pip install pug-brain[encryption]       # Encrypted storage
pip install pug-brain[all]              # All features

Cross-Language Recall (Optional)

# ~/.pugbrain/config.toml
[embedding]
enabled = true
provider = "auto"    # Ollama -> sentence-transformers -> Gemini -> OpenAI

How It Works

Query: "What did Alice suggest?"
  1. Decompose Query   -> time hints, entities, intent
  2. Find Anchors      -> "Alice" neuron
  3. Spread Activation -> activate connected neurons
  4. Find Intersection -> high-activation subgraph
  5. Extract Context   -> "Alice suggested rate limiting"

Concept	Description
Neuron	Memory unit (concept, entity, action, time, state, spatial, sensory, intent)
Synapse	Weighted, typed connection (CAUSED_BY, LEADS_TO, RESOLVED_BY, ...)
Fiber	Ordered neuron sequence forming a coherent memory trace
Spreading activation	Signal propagates from anchors through synapses, decaying with distance
Decay	Ebbinghaus forgetting curve — memories lose activation over time
Consolidation	Prune weak synapses, merge overlapping fibers, summarize clusters

CLI

# Store (type auto-detected)
pugbrain remember "Fixed auth bug in login.py:42"
pugbrain remember "We decided to use PostgreSQL" --type decision
pugbrain todo "Review PR #123" --priority 7

# Recall
pugbrain recall "auth bug"
pugbrain recall "database decision" --depth 2

# Shortcuts
pugbrain a "quick note"          # remember
pugbrain q "auth"                # recall
pugbrain last 5                  # recent memories
pugbrain today                   # today's memories

# Brain management
pugbrain brain list | create | use | health | export | import

# Maintenance
pugbrain decay                   # Forgetting curve
pugbrain consolidate             # Prune, merge, summarize
pugbrain index src/              # Index codebase