Forgetful MCP
MCP server with long-term memory for agents: atomic notes, semantic search and an auto-linked graph on SQLite or PostgreSQL
- 338 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- A persistent database keeps everything the agent decides to write, including repository descriptions and internal decisions
- In HTTP mode network access to the database is protected by authentication settings
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/forgetfulDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- A persistent database keeps everything the agent decides to write, including repository descriptions and internal decisions
- In HTTP mode network access to the database is protected by authentication settings
This is third-party code. Review the repository files before installing.
What it does
Forgetful runs as an MCP server and gives several agents one shared knowledge base. Claude Code, Cursor, Codex or a custom bot write notes into it and pull them back with a plain natural-language query. The server starts with `uvx forgetful-ai`, uses stdio by default, and HTTP mode switches on with `--transport http`. Each note holds one fact, following the Zettelkasten principle. Along with a title and body, the agent passes context, keywords and tags. From those fields the server builds embeddings, searches by meaning, reranks results with a cross-encoder and links similar notes into a graph on its own. The local FastEmbed library computes the embeddings, so no cloud calls are needed. Besides notes, Forgetful stores entities (people, organizations, products), projects, documents, code artifacts, skills in the SKILL.md format and plans with tasks for several agents. The client sees three meta-tools, including `discover_forgetful_tools` and `execute_forgetful_tool`, so descriptions of dozens of functions stay out of the context window. The `forgetful` command doubles as a terminal client: `forgetful memory save`, `forgetful memory search`.
Who it is for. Developers who work across several agents and want one shared memory: a sketch from Claude on a phone continues in Claude Code on a laptop.
Good fit when
- Decisions from a Claude Desktop discussion have to reach a Claude Code session without a manual recap
- An agent loses agreements about a repository between sessions, and you want to find them by meaning
- The base has to hold people, organizations and products together with links to notes
- Several agents share the work, and tasks with acceptance criteria live in one common plan
- Storage has to stay on your machine: SQLite on disk and embeddings without a cloud
Not a fit when
- A CLAUDE.md or AGENTS.md file with a couple of dozen rules is enough: a separate server is overkill
- You need a hosted service with support: Forgetful is self-deployed, together with Docker and PostgreSQL
- The client has no MCP support or company policy forbids connecting servers
- The machine is weak: embeddings and the cross-encoder run locally and load the CPU
Example request
Save to Forgetful that Stripe was chosen for the store redesign, and link the note to the Redesign projectMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
DATABASE- SQLite by default or Postgres for a shared deployment
FORGETFUL_TOKENsecret- Bearer token for the `forgetful` client against a remote server without a browser login
Limitations
- Python 3.12 or newer is required, and Docker too for a shared PostgreSQL server.
- The agent decides what to write and when. To make it consult memory regularly, the repository ships the `forgetful-remember` and `forgetful-recall` skills.
- Authentication for HTTP mode is set up separately, the options are listed in the FastMCP docs.
- The tool set depends on enabled feature flags, and `discover_forgetful_tools` returns the current list.
How to disable. Remove the forgetful block from mcpServers in the client config and restart the client. Data stays on disk: in `~/.local/share/forgetful` on Linux and macOS, in AppData on Windows. Delete that folder if the memory is no longer needed. Docker containers stop with `docker compose down`.
FAQ
How do I connect Forgetful to Claude Code?
Add an MCP block with type stdio, command `uvx` and argument `forgetful-ai`, then restart Claude Code. The steps for Claude Code, Cursor, Codex, Gemini CLI and OpenCode are in `docs/connectivity_guide.md` in the repository.
Where does Forgetful store notes?
In SQLite on your disk: `~/.local/share/forgetful` on Linux and macOS, AppData on Windows. For several users there is PostgreSQL via Docker Compose.
How is Forgetful different from a CLAUDE.md file?
A rules file is read in full at every start. Forgetful returns only the notes that match the query and shows the ones linked to them. That helps when there is more knowledge than fits in context.
Does Forgetful need cloud access?
Not for notes and search: the local FastEmbed library computes embeddings and the SQLite database sits on disk. The network is needed only in HTTP mode and with a remote server.
Can I use Forgetful from a terminal?
Yes. The `forgetful` command works as a client: `forgetful memory save` writes a note, `forgetful memory search` searches, and the `--json` flag gives machine-readable output. For a remote server use `forgetful auth login --server <address>`.
Discussion
No questions or reviews yet.
Related
MCP serversA self-hosted MCP memory server that keeps preferences and decisions across conversations in Claude Code, Cursor and other clients
Agent memory as a graph of linked facts: decisions and errors outlive the session, with no vector database or paid API calls
Self-hosted long-term memory for agents: semantic search, a knowledge graph and autonomous consolidation over MCP and a REST API
A long-term memory MCP server for agents: search, store and correct facts across sessions in the cloud or a local core
An MCP server for long-term agent memory: compresses dialogues into atomic facts, resolves pronouns and anchors relative time to absolute dates
A long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Forgetful (this card) | no | not required | 338 | |
| Basic Memory | no | not required | 4,509 | keeps memory in local Markdown files, while Forgetful stores atomic notes in SQLite or PostgreSQL |
| MCP Memory Service | no | not required | 2,090 | a self-hosted memory with a REST API and auto-consolidation |
| agentmemory | yes | not required | 30,160 | hooks record sessions on their own, in Forgetful the agent controls what gets written |
README in short
The README opens with an overview: the server enforces the Zettelkasten principle and builds a knowledge graph automatically. Next come installation from PyPI, from source and with Docker, connecting agents, the terminal client section, Python examples and an environment variable table. Links to the docs and contributor rules close the page.