🧠 Agent Brain: The Memory Module

Give your AI agents infinite, human-like long-term memory.

Agent Brain is a sophisticated memory system designed to transcend the limits of context windows. It doesn't just "store" data; it perceives, filters, consolidates, and recalls information just like the human brain.

🚀 Why Agent Brain?

Most "memory" solutions are just simple vector stores. Agent Brain is different. It implements a complete cognitive architecture:

• 🚫 Noise Filters (Salience Gating): Not everything is worth remembering. A dedicated "Gatekeeper" LLM evaluates every interaction for Importance, Stability, and Confidence.
• ⏱️ Short-Term Buffer: New memories aren't permanent. They live in a "working memory" buffer first.
• 💤 Sleep & Consolidation: A background process "dreams" (consolidates) memories, promoting high-value information to Long-Term Memory (LTM) and discarding decay.
• 🔌 Multi-Provider: Plug-and-play support for OpenAI (GPT-4) and Google Gemini (Gemini 2.0 Flash).

🏗️ Architecture

flowchart LR
    User[User Input] --> Ingest
    subgraph "Short-Term Processing"
        Ingest[Extraction LLM] --> Candidates
        Candidates --> Salience[Salience Gate]
        Salience -- "Low Value" --> Ignore[Discard]
        Salience -- "High Value" --> Buffer[Short-Term Buffer]
    end
    
    subgraph "Long-Term Memory"
        Buffer -- "Consolidate" --> LTM[(Vector Store)]
        LTM --> Retrieve[Semantic Search]
    end
    
    Retrieve --> Context[Agent Context]

⚡ Quick Start

1. Install

npm install agent-brain

2. Configure (Choose Your Brain)

Create a .env file:

# Choose OpenAI...
OPENAI_API_KEY=sk-...

# ...or Google Gemini
GEMINI_API_KEY=AIza...

3. Usage

import { MemoryEngine } from 'agent-brain';

// 1. Initialize
const brain = new MemoryEngine({
    dbPath: './memory.db',
    llmProvider: 'gemini', // or 'openai'
    llmModel: 'gemini-2.0-flash'
});

// 2. Ingest "Experience"
await brain.ingest({
    messages: [
        { role: 'user', content: "I'm working on a secret project called 'Project X'." },
        { role: 'assistant', content: "I'll keep that in mind." }
    ]
});
// 🧠 Brain: "Project X is active" -> Salience Score: 0.95 -> Stored in Buffer.

// 3. Consolidate (Sleep)
await brain.consolidate();
// 💤 Brain moves 'Project X' facts to Long-Term Memory.

// 4. Recall
const memories = await brain.retrieve({ 
    query: "What is the user working on?" 
});
console.log(memories[0].value); 
// Output: "User is working on a secret project called 'Project X'."

🧩 Features

| Feature | Description | Status | | :--- | :--- | :--- | | Semantic Memory | Facts, concepts, and world knowledge. | ✅ Ready | | Episodic Memory | Autobiographical events and user history. | ✅ Ready | | Procedural Memory | Instructions and preferences (e.g., "Always use JSON"). | ✅ Ready | | Vector Search | Semantic similarity search using embeddings. | ✅ Ready | | Salience Scoring | AI-driven evaluation of memory importance. | ✅ Ready | | Dual-Provider | Switch between OpenAI and Gemini instantly. | ✅ Ready |

🗺️ Roadmap

• [ ] Reinforcement Learning: Weight memories based on retrieval success.
• [ ] Graph Memory: Link entities in a knowledge graph logic.
• [ ] Active Forgetting: Decay unused memories over time.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Hitesh Gorana