# Engram — Cognitive Memory Infrastructure for AI Agents

> Engram is open-source cognitive memory infrastructure that gives AI agents persistent, typed memory inspired by human cognitive science. It is a self-hosted HTTP API backend built in Go with PostgreSQL and pgvector.

## What Engram Does

Engram provides AI agents with persistent memory that works like the human brain. Instead of losing context between conversations, agents using Engram can store, recall, and evolve memories over time. Memories strengthen with use, decay when forgotten, and update from feedback.

## The Problem Engram Solves

- AI agents forget everything between sessions — Engram gives them persistent memory
- RAG and vector databases treat all information equally — Engram uses confidence-based tiering to prioritize what matters
- Agents can't detect contradictory information — Engram's belief dynamics surface conflicts
- No mechanism for agents to learn from experience — Engram implements cognitive learning patterns
- Context windows overflow with retrieved information — Engram's tiering auto-injects only high-confidence memories

## Four Memory Systems (Inspired by Cognitive Science)

1. **Semantic Memory** — Facts, preferences, beliefs, and decisions. Typed and confidence-scored. Example: "User prefers dark mode" (confidence: 0.92)
2. **Episodic Memory** — Rich records of past interactions with full context, emotions, entities, causal links, and outcomes. Example: "Helped debug authentication flow — resolved successfully"
3. **Procedural Memory** — Learned skills and trigger-action patterns extracted from successful episodes. Example: "When error occurs → check logs first" (success rate: 87%)
4. **Working Memory** — 7-slot active memory for current goals, reasoning state, and recent messages. Mirrors human working memory capacity.

## Key Features

- **Confidence-Based Tiering**: Memories are auto-tiered into Hot (>0.85, auto-injected), Warm (0.70-0.85, on-demand), Cold (0.40-0.70, explicit query), Archive (<0.40, soft-deleted)
- **Belief Dynamics**: Bayesian log-odds confidence updates. Reinforced memories strengthen (+0.05), contradicted memories weaken (-0.2), unused memories decay naturally, recalled memories get a small boost (+0.02)
- **Hybrid Retrieval**: Every recall combines vector similarity search with knowledge graph traversal up to 2 hops deep
- **Conversation Extraction**: Automatically extract memories from conversation transcripts using LLM-powered classification
- **Procedural Learning**: Agents learn skills from successful episodes as trigger-action patterns
- **Metacognition**: Agents can assess their own knowledge quality, detect gaps, and flag uncertainty
- **Multi-LLM Support**: Works with OpenAI, Anthropic Claude, Google Gemini, and Cerebras
- **40+ API Endpoints**: Comprehensive REST API for all memory operations
- **Sub-10ms p95 Recall Latency**: Fast memory retrieval for real-time agent interactions
- **Multi-Tenant**: Per-agent memory isolation with API key authentication

## Tech Stack

- **Go** — Single binary, zero runtime dependencies
- **PostgreSQL** — Battle-tested relational storage
- **pgvector** — Native vector similarity search
- **Docker** — One-command deployment via Docker Compose

## Who Engram Is For

- **AI Agent Developers** building conversational agents, copilots, or assistants that interact with users over time
- **LLM App Builders** shipping products that need persistent user context beyond a single session
- **Multi-Agent Systems** needing shared memory with automatic conflict resolution
- **Research Teams** implementing cognitive architectures grounded in CoALA, Mem0, ACT-R, and MUSE research

## Who Engram Is NOT For

- Projects that only need simple key-value storage
- Teams looking for a standalone vector database
- Single-turn, stateless bot builders

## Research Foundations

Engram is grounded in peer-reviewed cognitive science research:
- **CoALA** (Cognitive Architectures for Language Agents) — Framework for structured agent memory
- **Mem0** — Graph-based memory showing 26% improvement in retrieval quality
- **ACT-R** — Memory activation and decay principles
- **Ebbinghaus Forgetting Curves** — Time-based memory decay modeling
- **MUSE** — Metacognitive frameworks for agent self-assessment

## Comparison to Alternatives

| Feature | Engram | Vector DB (Pinecone, Weaviate) | RAG Systems | Mem0 |
|---------|--------|-------------------------------|-------------|------|
| Typed memory systems | 4 types | No | No | Partial |
| Confidence tiering | Yes | No | No | No |
| Belief dynamics | Bayesian | No | No | No |
| Graph + vector retrieval | Hybrid | Vector only | Vector only | Graph |
| Memory decay | Yes | No | No | No |
| Procedural learning | Yes | No | No | No |
| Metacognition | Yes | No | No | No |
| Self-hosted | Yes | Varies | Varies | Cloud |
| Open source | MIT | Varies | Varies | Partial |

## Quick Start

```bash
# 1. Start the server
docker compose up -d

# 2. Create an agent
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "my-agent"}'

# 3. Store a memory
curl -X POST http://localhost:8080/v1/memories \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"agent_id": "...", "content": "User prefers dark mode", "memory_type": "preference"}'

# 4. Recall memories
curl http://localhost:8080/v1/memories/recall?query="user+preferences"&agent_id=...
```

## Links

- Website: https://engram.to
- GitHub: https://github.com/Harshitk-cp/engram
- License: MIT (fully open source)