Forgetful is a Python-based MCP server that provides a persistent memory store and retrieval system for AI agents. It follows the Model Context Protocol (MCP) and exposes a compact, opinionated feature set to simplify how agents store atomic memories, associated context, keywords, and tags, and then retrieve them via natural language queries. The server supports two transport modes: STDIO (recommended for local development) and HTTP (for Docker/remote deployments). Through the meta-tools pattern, Forgetful surfaces a small, stable set of core tools to MCP clients, while a larger arsenal of tools is accessible via the execute_forgetful_tool pathway, enabling flexible memory operations without overwhelming the client with options. The system also automatically links memories to related items to build a lightweight knowledge graph, and supports entities, projects, documents, and code artifacts as part of the memory ecosystem.

To use Forgetful, connect an MCP client (such as a Coding Agent or an in-house agent) via the stdio or HTTP transport. For stdio, configure the MCP client to run the uvx forgetful-ai command, which starts the server in stdio mode and communicates over the standard input/output channels. For HTTP, point the client at the HTTP endpoint exposed by Forgetful (e.g., http://localhost:8020/mcp) and use the HTTP transport configuration. The server enables a meta-tools pattern, which exposes three core tools directly to the client; additional capabilities are exposed through the documented tool reference, allowing you to extend memory creation, querying, and linking workflows as needed. Remember that Forgetful emphasizes atomic memories (per the Zettelkasten principle) and semantic embeddings for retrieval, so craft memories with a clear title, content, context, keywords, and tags to maximize recall quality.

Prerequisites:

• Python 3.12 or newer installed on your system
• Internet access to install dependencies via uvx or the project setup

Option A: Install and run Forgetful via uvx (recommended for development and quick experiments)

1. Ensure Python is installed (3.12+)
2. Install the Forgetful package and run the server using uvx: uvx forgetful-ai

   or install globally and run

   uv tool install forgetful-ai forgetful

Option B: Run Forgetful from source (development workflow)

1. Clone the repository: git clone https://github.com/ScottRBK/forgetful.git cd forgetful
2. Install dependencies via uv (or pip) and synchronize sources: uv sync
3. Run the server (default SQLite storage): uv run main.py

   For HTTP transport, add the flag: --transport http

Option C: Docker deployment (production/scale) SQLite with Docker (simpler)

1. Navigate to docker directory and prepare environment: cd docker cp .env.example .env

   Edit .env to set DATABASE=SQLite and SQLITE_PATH as needed

2. Start the containers: docker compose -f docker-compose.sqlite.yml up -d

PostgreSQL with Docker (recommended for multi-tenant deployments)

1. Navigate to docker directory: cd docker cp .env.example .env

   Edit .env to configure DATABASE=Postgres and POSTGRES_* settings

2. Start the containers: docker compose -f docker-compose.postgres.yml up -d

Notes:

• If no .env file exists, Forgetful will use defaults from app/config/settings.py.
• For full configuration options, see the Configuration Guide in docs/configuration.md.

Tips and common considerations:

• Transport choice: Use stdio for local development and testing; use HTTP for Dockerized or remote deployments.
• Data persistence: The SQLite store persists under data/ by default; for production, consider PostgreSQL for multi-tenant setups.
• Environment variables: You can customize database type and paths via the .env file when using Docker; consult the documentation for specific POSTGRES_ and SQLITE_ environment variables.
• Connectivity: Add Forgetful to your MCP client configuration with either stdio (recommended for local use) or HTTP transport (for Docker/remote setups).
• If you encounter transport or embedding issues, verify that the MCP client is aligned with the three core tools exposed by Forgetful and that the client is using the correct tool invocation patterns (e.g., execute_forgetful_tool for extended capabilities).