Forgetful
Forgetful is an MCP semantic-memory and knowledge-management server that exposes three meta-tools for agents to discover, inspect, and execute underlying tools.
Discover available tools by category and get detailed parameter docs/usage examples.
Execute registered tools dynamically with
execute_forgetful_tool.Create, search, retrieve, update, link/unlink, obsolete/restore, and list recent memories.
Track memory provenance, source files/repos/URLs, confidence, and encoding agent/version.
Organize knowledge with projects and project-scoped searches.
Manage entities (people, organizations, devices), aliases, entity-memory/project links, and typed relationships.
Store and manage long-form documents and reusable code artifacts.
Manage user profile notes/preferences; optional feature-flag tools may add skills, plans, and tasks.
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., "@Forgetful search for memories about Zettelkasten method"
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.
Forgetful is a storage and retrieval tool for AI Agents. Designed as a Model Context Protocol (MCP) server built using the FastMCP framework. Once connected to this service, MCP clients such as Coding Agents, Chat Bots or your own custom built Agents can store and retrieve information from the same knowledge base.

Table of Contents
Related MCP server: local-memory-mcp
Overview
A lot of us are using AI Agents now, especially in the realm of software development. The pace at which work and decisions are made can make it difficult for you to keep up from a notes and context persistence perspective.
So if you are following something like the BMAD Method for example and you want to take your brain storming session you've just had with Claude on your desktop/mobile and use it for the basis of your next Claude Code session, then having a shared knowledge base across the two agents can help with this.
This is just one example use case to illustrate the point, more and more agentic applications are going to surface and the use cases for sharing data across them is going to increase.
Knowledge bases are going to become a key infrastructure component for your interactions with AIs. There are many excellent knowledge base solutions available (many for free on github) and I would encourage you to check them out and find one that works for you (even if Forgetful doesn't) as I found from personal experience that interactions with my agents got easier and more rewarding once they knew more about me, my work and previous interactions that I had had with them or other AI systems.
What makes Forgetful different from other Memory based MCP services is that it is a rather opinionated view on how AI Agents such store and retrieve data.
Forgetful imposes the Zettelkasten principle when clients wish to record memories, that is each memory must be atomic (one concept per note). Along with the note (title and content), we also ask the client / agent to provide context around what it was doing when creating the note, along with keywords and tags. With this information we create semantic embeddings and store these to aid with later retrieval and in addition to this we also automatically link the memory to existing memories that have a particular similarity score, allowing for the automatic construction of a knowledge graph.
In this sense Forgetful becomes a little bit like Obsidian for AI Agents, where the auto linking nudges them in building up a graph of the knowledge.
We find, as do others (A-MEM: Agentic Memory or LLM Agents), all this helps in ensuring that when the agent requires relevant information from the memory system later, the correct information is returned.
In addition to just memories, Forgetful also has the concept of entities (think organisation, people, products), projects, documents, code artifacts, skills (procedural knowledge following the Agent Skills standard), and plans with tasks for multi-agent coordination, all of which can be associated with one or more memories.

Features
Configure either STDIO or HTTP transport mechanism (or stand up two services to support both)
Multiple Authentication supported, flows see FastMCP docs for full list
Meta Tool Discovery, only three tools exposed to client application to preserve context window.
Flexible Storage– SQLite (default, zero-config) or PostgreSQL (for scale and production deployments)
Stores memories as vectors and allowing memories to be retrieved from natural language queries from AI.
Cross Encoder reranking to improve recall and precision of memory retrieval.
Flexible ranking (embedding and cross encoder) providers, run everything locally without calls to the cloud thanks to FastEmbed
Automatic linking of semantically similar memories, automating the creation of the knowledge graph.
Plans and Tasks for multi-agent coordination -- structure work into plans with tasks that have acceptance criteria, state management with optimistic locking, and dependency tracking with cycle detection.
Skills for procedural memory -- store step-by-step instructions and agent capabilities with semantic search, import/export in Agent Skills SKILL.md format, and cross-referencing with memories.
For the complete roadmap, see Features Roadmap.
Quick Start
Option 1: PyPI (Recommended)
# Run directly with uvx (no installation needed)
uvx forgetful-ai
# Or install globally
uv tool install forgetful-ai
forgetfulData stored in platform-appropriate locations (~/.local/share/forgetful on Linux/Mac, AppData on Windows).
By default, runs with stdio transport for MCP clients. For HTTP:
uvx forgetful-ai --transport http --port 8020Option 2: From Source
git clone https://github.com/ScottRBK/forgetful.git
cd forgetful
# Install dependencies with uv
uv sync
# Run the server (uses SQLite by default)
uv run main.pyThe server starts with stdio transport. For HTTP: uv run main.py --transport http
Option 3: Docker Deployment (Production/Scale)
Forgetful provides two Docker deployment options:
SQLite with Docker (Simpler, Single-Container)
cd docker
cp .env.example .env
# Edit .env: Set DATABASE=SQLite and SQLITE_PATH=data/forgetful.db
docker compose -f docker-compose.sqlite.yml up -dThe SQLite database persists in the ./data directory on the host.
PostgreSQL with Docker (Recommended for multitenant)
See docker-compose.postgres.yml and .env.example
cd docker
cp .env.example .env
# Edit .env: Set DATABASE=Postgres and configure POSTGRES_* settings
docker compose -f docker-compose.postgres.yml up -dNote: If no .env file exists, the application uses defaults from app/config/settings.py.
For all configuration options, see Configuration Guide.
Connecting to An Agent
For detailed connection guides (Claude Code, Claude Desktop, other clients that support MCP), see Connectivity Guide.
Copilot CLI (includes custom agents and skills)
Gemini CLI (includes custom commands)
Opencode (includes custom commands and skills)
Add Forgetful to your MCP client configuration:
stdio transport (recommended for local use):
{
"mcpServers": {
"forgetful": {
"type": "stdio",
"command": "uvx",
"args": ["forgetful-ai"]
}
}
}HTTP transport (for Docker/remote):
{
"mcpServers": {
"forgetful": {
"type": "http",
"url": "http://localhost:8020/mcp"
}
}
}CLI
The forgetful command is also a full terminal client over the same tool registry the
MCP meta-tools use - against your local database by default, or a remote deployment
after auth login.
uv tool install forgetful-ai
# Curated verbs for daily use
forgetful memory save "Set generateResolvConf false to fix WSL2 DNS" \
--title "WSL2 DNS fix" --importance 7
forgetful memory search "wsl dns" -c "wsl networking" -n 5
forgetful memory get 812
forgetful memory recent -n 10 -p my-project
forgetful project list
# Generic passthrough to any available tool
forgetful tools list --category memory
forgetful tools info query_memory
forgetful call create_project --args '{"name": "Homelab", "description": "...", "project_type": "personal"}'
# Remote deployment (browser OAuth; saves FORGETFUL_SERVER to ~/.config/forgetful/.env)
forgetful auth login --server https://forgetful.example.com
forgetful auth status
forgetful memory search "wsl dns" -c "wsl networking" # now runs remotely
forgetful memory search "wsl dns" -c "wsl networking" --local # force local mode per invocation
# Scripting: --json emits machine-readable output
forgetful memory search "wsl dns" -c "wsl networking" --json | jq '.primary_memories[0].id'forgetful serve is the canonical way to run the MCP server (forgetful serve --transport http --port 8020); the bare forgetful / uvx forgetful-ai invocation and
the legacy --transport/--re-embed flags keep working indefinitely, so existing MCP
client configurations are unaffected. Headless environments can set FORGETFUL_TOKEN
(bearer) instead of the OAuth flow. See the
Configuration Guide for precedence rules, or walk
through the forgetful-cli-setup skill for install,
auth, and verification steps end-to-end.
Usage Examples
Forgetful exposes only 3 meta-tools to MCP clients. The tools available through
execute_forgetful_tool depend on the enabled feature flags. Use
discover_forgetful_tools for the current runtime catalog.
Example 1: Project-Scoped Memory
Create a memory linked to a project for better organization and scoped retrieval.
# Create project for organizing related knowledge
project = execute_forgetful_tool(
"create_project",
{
"name": "E-Commerce Platform Redesign",
"project_type": "work",
"status": "active"
}
)
# Create memory linked to project
memory = execute_forgetful_tool(
"create_memory",
{
"title": "Payment gateway: Stripe chosen over PayPal",
"content": "Selected Stripe for its API, fees, and fraud detection.",
"context": "Choosing the payment provider for the redesign",
"keywords": ["payment", "stripe", "paypal"],
"tags": ["payment", "decision"],
"importance": 9,
"project_ids": [project["id"]]
}
)
# Later, query within project scope
results = execute_forgetful_tool(
"query_memory",
{
"query": "payment processing implementation",
"query_context": "Implementing payments for the redesign",
"project_ids": [project["id"]]
}
)
# Returns: Stripe decision + auto-linked related memoriesExample 2: Knowledge Graph with Entities
Track people, organizations, and relationships - perfect for team and infrastructure management.
# New engineer joins your company
new_hire = execute_forgetful_tool(
"create_entity",
{
"name": "Jordan Taylor",
"entity_type": "Individual",
"description": "Backend Engineer - Payments Team",
"tags": ["engineering", "backend", "payments"]
}
)
# Get company entity (create if needed)
company = execute_forgetful_tool(
"create_entity",
{
"name": "TechFlow Systems",
"entity_type": "Organization",
"description": "SaaS platform company"
}
)
# Create employment relationship
execute_forgetful_tool(
"create_entity_relationship",
{
"from_entity_id": new_hire["id"],
"to_entity_id": company["id"],
"relationship_type": "works_for",
"metadata": {
"role": "Backend Engineer II",
"department": "Payments",
"start_date": "2025-01-20"
}
}
)
# Create memory about hiring
hire_memory = execute_forgetful_tool(
"create_memory",
{
"title": "Jordan Taylor hired - payments focus",
"content": "Jordan joins to build the Stripe integration and handle PCI compliance.",
"context": "Recording ownership and experience for the payments work",
"keywords": ["jordan", "stripe", "payments", "pci"],
"tags": ["team", "hiring", "payments"],
"importance": 7
}
)
# Link person to memory
execute_forgetful_tool(
"link_entity_to_memory",
{
"entity_id": new_hire["id"],
"memory_id": hire_memory["id"]
}
)
# Query Jordan's related knowledge
results = execute_forgetful_tool(
"query_memory",
{
"query": "Jordan payment implementation",
"query_context": "Finding ownership and experience for payments work"
}
)
# Returns: Hiring memory + linked entity + relationship contextTool Categories
The core catalog covers users, memories, projects, entities, code artifacts, and documents. Skills, files, plans, and tasks appear when their feature flags are enabled.
For complete documentation with extensive examples, see Complete Tool Reference.
How It Works
Atomic Memory Principle
Inspired by Zettelkasten, each memory stores one concept in ~300-400 words:
Easily titled – Forces clarity (200 char limit)
Self-contained – Understandable without external context
Linkable – Small units enable precise knowledge graphs
For detailed content, use Documents and extract 3-7 atomic memories that link to the parent document.
Automatic Knowledge Graph
When you create a memory:
Embedding generated – FastEmbed converts content to 384-dimensional vector
Similarity search – Finds related memories (similarity ≥0.7 by default)
Auto-linking – Creates bidirectional links to top 3-5 matches (configurable)
Graph traversal – Queries return primary results + 1-hop linked memories
Entities and Knowledge Graphs
Entities represent concrete, real-world things (people, organizations, teams, devices) that can be linked to memories:
Typed entities – Organizations, Individuals, Teams, Devices, Systems, or custom types
Relationships – Directional connections (e.g., "Person works_at Organization") with strength and metadata
Memory linking – Associate entities with relevant memories for context
Knowledge graph – Build networks showing how entities relate to each other and your knowledge base
Use entities for concrete things (Sarah Chen, TechFlow Systems, Cache Server 01) and memories for abstract concepts (architectural patterns, decisions, learnings).
Token Budget Management
Prevents context window overflow:
Configurable budget (default 8K tokens)
Search finds relevant memories; primary results are then sorted by importance (high first)
Equal-importance primary results keep their search order, even when nothing is truncated
Truncates gracefully if over budget
Respects max memory count (default 20)
This keeps query results within the LLM's context budget.
For vector search and optional cross-encoder reranking, see Search Documentation.
Configuration
No configuration required – Forgetful uses sensible defaults out of the box.
Key Settings (Optional)
MEMORY_TOKEN_BUDGET– Max tokens for query results (default:8000)EMBEDDING_MODEL– Embedding model (default:BAAI/bge-small-en-v1.5)MEMORY_NUM_AUTO_LINK– Auto-link count (default:3, set0to disable)MEMORY_SIMILARITY_THRESHOLD– Minimum cosine similarity for auto-links (default:0.7)SERVER_PORT– HTTP server port (default:8020)MAX_GRAPH_LIMIT– Upper bound for/api/v1/graph?limitand/api/v1/graph/subgraph?max_nodes(default:2000)
For all 40+ environment variables with detailed explanations, see Configuration Guide.
Documentation
Guides
Core Concepts – Memories vs Entities vs Documents explained
Complete Tool Reference – Runtime tools and examples
REST API Reference – HTTP endpoints for web UI integration
Configuration Guide – All environment variables explained
Connectivity Guide – Connect Claude and other MCP clients
Self-Hosting Guide – Deploy on a VPS with Docker
Nix Guide – Reproducible dev shell, builds and OCI image with Nix flakes
Search Documentation – Embedding pipeline and retrieval architecture
Embedding Migration – Switch embedding providers safely
Features Roadmap – Planned features and priorities
External Resources
MCP Protocol Specification – Model Context Protocol docs
pgvector – PostgreSQL vector extension
FastEmbed – Local embedding generation
Zettelkasten Principle – Atomic note-taking method
Contributing
We welcome contributions! Forgetful uses integration + E2E testing with Docker Compose orchestration.
See the contributor guide for:
Testing workflows (integration tests, E2E tests, GitHub Actions)
Development setup (local vs Docker)
CI/CD pipeline details
Release process
License
MIT License - see LICENSE for details.
Available Tools
3 toolsdiscover_forgetful_toolsA
Discover available tools, optionally filtered by category
Returns enough information for LLMs to call tools directly without needing how_to_use.
Inputs: category. Returns: object
execute_forgetful_toolA
Execute any registered tool dynamically. Forgetful is a semantic memory system for LLMs.
Quick Start - One-Shot Examples (all required params shown)
Memory Operations:
Search: execute_forgetful_tool("query_memory", {"query": "search terms", "query_context": "why searching"})
Create: execute_forgetful_tool("create_memory", {"title": "Short title", "content": "Memory content (<2000 chars)", "context": "Why this matters", "keywords": ["kw1", "kw2"], "tags": ["tag1"], "importance": 7, "project_ids": [1]})
Create with provenance: execute_forgetful_tool("create_memory", {"title": "...", "content": "...", "context": "...", "keywords": [...], "tags": [...], "importance": 7, "source_repo": "owner/repo", "source_files": ["src/main.py"], "confidence": 0.85, "encoding_agent": "claude-sonnet-4"})
Update: execute_forgetful_tool("update_memory", {"memory_id": 1, "content": "new content"})
Get: execute_forgetful_tool("get_memory", {"memory_id": 1})
Link: execute_forgetful_tool("link_memories", {"memory_id": 1, "related_ids": [2, 3]})
Unlink: execute_forgetful_tool("unlink_memories", {"source_id": 1, "target_id": 2})
Obsolete: execute_forgetful_tool("mark_memory_obsolete", {"memory_id": 42, "reason": "Outdated approach", "superseded_by": 100})
Project Organization:
List: execute_forgetful_tool("list_projects", {})
Create: execute_forgetful_tool("create_project", {"name": "Project Name", "description": "What this project is about", "project_type": "development"})
Get: execute_forgetful_tool("get_project", {"project_id": 1})
Query: execute_forgetful_tool("query_memory", {"query": "search terms", "query_context": "why searching", "project_ids": [1]})
Entities (people, orgs, devices):
Create: execute_forgetful_tool("create_entity", {"name": "Sarah Chen", "entity_type": "Individual", "notes": "Backend developer", "aka": ["Sarah", "S.C."]})
Search: execute_forgetful_tool("search_entities", {"query": "Sarah"}) # Searches name AND aka
Link to memory: execute_forgetful_tool("link_entity_to_memory", {"entity_id": 1, "memory_id": 1})
Unlink from memory: execute_forgetful_tool("unlink_entity_from_memory", {"entity_id": 1, "memory_id": 1})
Link to project: execute_forgetful_tool("link_entity_to_project", {"entity_id": 1, "project_id": 1})
Unlink from project: execute_forgetful_tool("unlink_entity_from_project", {"entity_id": 1, "project_id": 1})
Documents (long-form content >300 words):
Create: execute_forgetful_tool("create_document", {"title": "Doc Title", "description": "Brief summary", "content": "Long content...", "document_type": "text", "project_id": 1})
Code Artifacts (reusable snippets):
Create: execute_forgetful_tool("create_code_artifact", {"title": "Snippet Title", "description": "What this does", "code": "def example(): pass", "language": "python", "project_id": 1})
Linking Best Practices
Always link related items for discoverability:
When creating documents, link atomic memories:
create_memory(..., document_ids=[doc_id])When creating code artifacts, link to memories:
create_memory(..., code_artifact_ids=[artifact_id])Link memories to each other:
link_memories(memory_id=1, related_ids=[2, 3])Link entities to memories:
link_entity_to_memory(entity_id=1, memory_id=1)Link entities to projects:
link_entity_to_project(entity_id=1, project_id=1)
Tool Categories
memory | project | entity | document | code_artifact | linking | user
Use discover_forgetful_tools(category?) for full parameter details and optional params.
Inputs: arguments (required), tool_name (required).
how_to_use_forgetful_toolB
Get detailed documentation for a specific tool
Returns complete documentation including JSON schema, multiple examples, and full parameter details.
Inputs: tool_name (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools form a clean meta-pattern: discovery, documentation, and execution each have a distinct role, and the execute tool's description enumerates the vast underlying tool surface. The only mild overlap is between discover_forgetful_tools and how_to_use_forgetful_tool, both of which return tool information, though one is a list/browse and the other is deep per-tool docs.
All three names are snake_case and share a consistent '<verb>_forgetful_tool(s)' suffix, making the family immediately recognizable. Minor deviations occur: 'how_to_use' is a phrase rather than a single verb, and the singular/plural suffixes (tools vs tool) are inconsistent across the three.
Three tools is thin on its face, but this is a deliberate gateway/dynamic-tool pattern where execute_forgetful_tool fronts dozens of memory, project, entity, document, and artifact operations, so the small top-level surface is appropriate rather than impoverished. Each of the three tools clearly earns its place with no redundancy.
The underlying surface described in the execute documentation covers near-full lifecycle: create/get/update/query/obsolete and linking for memories, CRUD-ish operations for projects, entities, documents, and code artifacts, plus entity-memory and entity-project linking. Hard deletes and cross-resource search are the only plausible gaps, and discovery-plus-execute means the surface is self-revealing rather than dead-ending.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePersistent semantic memory server for AI assistants via MCP, enabling long-term context retention and semantic search across conversations.12MIT
- FlicenseNot gradedqualityDmaintenanceA local MCP server that provides semantic memory storage and retrieval for coding and AI agents, enabling durable context across chat sessions.4-
- FlicenseNot gradedqualityBmaintenanceA persistent memory server for AI agents using MCP protocol, enabling semantic storage and retrieval of dialogues, documents, and agent states.-
- AlicenseNot gradedqualityDmaintenanceUniversal MCP server providing adaptive semantic memory for AI agents, supporting document ingestion, semantic search, chat persistence, cross-project linking, and cloud storage overflow.3GPL 3.0