Forgetful

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

• Overview
• Features
• Quick Start
• CLI
• Some Examples
• How It Works
• Configuration
• Documentation
• Contributing
• License

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
forgetful

Data 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 8020

Option 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.py

The 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)

See docker-compose.sqlite.yml

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 -d

The 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 -d

Note: 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.

• Claude Code
• VS Code
• Copilot CLI (includes custom agents and skills)
• Cursor
• Codex
• 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" -n 5
forgetful memory get 812
forgetful memory recent -n 10 -p my-project
forgetful project list

# Generic passthrough to any of the 42 tools
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"          # now runs against the remote server
forgetful memory search "wsl dns" --local  # force local mode per invocation

# Scripting: --json emits machine-readable output
forgetful memory search "wsl dns" --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.

Usage Examples

Forgetful exposes tools