v3.0 · Open Source · MIT License

The Memory Layer
for AI Agents

Your agents forget everything between sessions. Qoopia fixes that. Universal notes, full-text search, session history, agent management — all through MCP. Three dependencies. One SQLite file.

Get Started See How It Works
# Install and run
git clone https://github.com/qoopia/qoopia
cd qoopia && bun install
bun run start

# MCP endpoint ready at localhost:3737
# Connect any agent via Streamable HTTP
3
Dependencies
28
Source Files
MCP
Streamable HTTP
SQLite
WAL Mode
Why Qoopia?
AI agents lose everything between sessions. Qoopia gives them persistent memory, shared context, and a unified knowledge base through the Model Context Protocol.
📝
Universal Notes
One table for everything: tasks, deals, contacts, memories, decisions, knowledge, context. Each note has a type, metadata, tags, and full-text search. No schema migrations when your needs change.
🔍
Full-Text Search
FTS5 with unicode61 tokenizer across all notes and session messages. recall() finds anything in milliseconds. Prefix matching, diacritics removal, workspace-scoped.
💬
Session History
Agents save conversation messages, write summaries, search across sessions. session_recent('latest') restores full context in one call. Cross-session search included.
🔗
MCP Native
Built on @modelcontextprotocol/sdk. Streamable HTTP transport, stateless mode. Works with Claude.ai, Claude Code, or any MCP client. OAuth 2.0 PKCE for remote connections.
👥
Multi-Agent
Multiple agents share one database. Each has its own API key, permissions, and audit trail. Steward agents manage other agents. Activity log tracks who did what.
🔒
Secure by Default
API key auth (SHA-256) + OAuth 2.0 PKCE. Rate limiting. CORS allowlist. Secret guard prevents API keys from leaking into notes. Workspace isolation.
⚡
Minimal & Fast
Three dependencies: @modelcontextprotocol/sdk, zod, ulid. Runs on Bun. No ORM, no framework, no build step. ~4,700 lines of TypeScript. Starts in under a second.
💾
Self-Hosted
Your data stays on your machine. One SQLite file, no cloud, no vendor lock-in. Daily automated backups with rotation. Runs anywhere Bun runs.
🔄
V2 Compatible
Migrating from V2? The compat layer maps old CRUD tools (list, get, create, update, delete) to universal notes. Zero downtime migration with included scripts.
How It Works
Three steps to give your agents persistent memory.
01
Deploy Qoopia
Clone, bun install, bun run start. Qoopia listens on port 3737. SQLite database created automatically. Install as a system service with one command.
02
Connect Agents
Add Qoopia as an MCP server in your agent config with a Bearer token. Or connect Claude.ai via OAuth. Each agent gets its own API key and audit trail.
03
Agents Remember
Agents call brief() to restore context, recall() to search knowledge, note_create() to save discoveries. Session messages persist across restarts.
Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Agent 1 │ │ Agent 2 │ │ Agent N │ │ Claude Code │ │ Claude.ai │ │ Any MCP │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ MCP (Streamable HTTP) │ OAuth 2.0 │ └───────────────┬──────────────┘ │ ┌────────┴────────┐ │ Qoopia V3 │ │ Bun + MCP SDK │ │ 13 native tools │ │ + V2 compat │ │ + admin tools │ └────────┬────────┘ │ ┌────────┴────────┐ │ SQLite + WAL │ │ Universal notes │ │ FTS5 search │ │ Sessions + audit │ └─────────────────┘
MCP Tools
13 native tools + 6 V2 compat aliases + 3 admin tools. Everything an agent needs to remember, search, and manage.
recallFull-text search across notes & activity
briefWorkspace snapshot: tasks, notes, deals, agents
note_createCreate any type: task, deal, memory, decision...
note_getFetch a single note by ID
note_listList with filters: type, tags, status, date range
note_updateUpdate text, metadata (shallow merge or replace)
note_deleteSoft-delete (recoverable)
session_saveAppend message to session history
session_recentLoad recent messages ('latest' supported)
session_searchFTS5 search across all saved sessions
session_summarizeSave agent-written summary of message range
session_expandFetch raw messages by ID range
activity_listAudit log with filters
agent_onboardSteward: create agent + bootstrap notes
agent_listSteward: list all agents in workspace
agent_deactivateSteward: deactivate agent + revoke tokens
Use Cases
Built for teams of AI agents that need to share knowledge and maintain context across sessions.
Multi-Agent Teams
Run 3-7 Claude Code agents on Telegram, each with their own role. They all write to Qoopia, see each other's tasks, and maintain shared context. One agent's discovery becomes everyone's knowledge.
Business Operations
Track deals, contacts, tasks with full history. Operations manager agent coordinates team, creates tasks, tracks completion. All searchable, all audited.
Session Continuity
Agent crashes at 3am, restarts at 3:01. Calls session_recent('latest') — full context restored. No lost conversations, no repeated questions.
Knowledge Management
Agents save rules, decisions, context notes. recall() finds relevant knowledge in milliseconds. Build institutional memory that compounds over time.

Give your agents memory

Three dependencies. One SQLite file. All the memory your agents need.

bun install && bun run start


View on GitHub