{"id":51042324,"url":"https://github.com/ScottRBK/forgetful","last_synced_at":"2026-07-10T13:00:55.959Z","repository":{"id":319903517,"uuid":"1079822299","full_name":"ScottRBK/forgetful","owner":"ScottRBK","description":"Opensource Memory for Agents","archived":false,"fork":false,"pushed_at":"2026-06-05T18:09:44.000Z","size":8384,"stargazers_count":274,"open_issues_count":1,"forks_count":23,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-05T20:07:27.154Z","etag":null,"topics":["ai-agents","ai-memory","claude-code","long-term-memo","mcp","memory"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ScottRBK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-20T12:47:45.000Z","updated_at":"2026-06-05T18:09:47.000Z","dependencies_parsed_at":"2025-10-22T00:06:18.982Z","dependency_job_id":null,"html_url":"https://github.com/ScottRBK/forgetful","commit_stats":null,"previous_names":["scottrbk/veridian","scottrbk/memento-ai","scottrbk/forgetful"],"tags_count":36,"template":false,"template_full_name":"ScottRBK/python_template","purl":"pkg:github/ScottRBK/forgetful","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScottRBK%2Fforgetful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScottRBK%2Fforgetful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScottRBK%2Fforgetful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScottRBK%2Fforgetful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ScottRBK","download_url":"https://codeload.github.com/ScottRBK/forgetful/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScottRBK%2Fforgetful/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35331955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-memory","claude-code","long-term-memo","mcp","memory"],"created_at":"2026-06-22T12:00:19.533Z","updated_at":"2026-07-10T13:00:55.952Z","avatar_url":"https://github.com/ScottRBK.png","language":"Python","funding_links":[],"categories":["4. Agentic AI \u0026 Multi-Agent Systems"],"sub_categories":[],"readme":"# Forgetful\n\n![Python](https://img.shields.io/badge/python-3.12%2B-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![MCP](https://img.shields.io/badge/MCP-server-purple)\n[![FastMCP](https://img.shields.io/badge/FastMCP-powered-orange)](https://github.com/jlowin/fastmcp)\n[![FastEmbed](https://img.shields.io/badge/FastEmbed-powered-orange)](https://github.com/qdrant/fastembed)\n[![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da?logo=discord\u0026logoColor=white)](https://discord.gg/ngaUjKWkFJ)\n\n\n**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. \n\n![Banner](/docs/images/layers.png)\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [CLI](#cli)\n- [Some Examples](#usage-example)\n- [How It Works](#how-it-works)\n- [Configuration](#configuration)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\nA 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. \n\nSo if you are following something like the [BMAD Method](https://github.com/bmad-code-org/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. \n\nThis 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. \n\nKnowledge 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. \n\nWhat 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.\n\n**Forgetful** imposes the [Zettelkasten principle](https://en.wikipedia.org/wiki/Zettelkasten) 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. \n\nIn 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.\n\nWe find, [as do others (A-MEM: Agentic Memory or LLM Agents)](https://arxiv.org/abs/2502.12110), all this helps in ensuring that when the agent requires relevant information from the memory system later, the correct information is returned.\n\nIn 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](https://agentskills.io) standard), and plans with tasks for multi-agent coordination, all of which can be associated with one or more memories.\n\n\n![Architecture](docs/images/Forgetful%20Architecture.drawio_transparent.png)\n\n## Features\n- Configure either **STDIO** or **HTTP** transport mechanism (or stand up two services to support both)\n- Multiple Authentication supported, flows see [FastMCP docs](https://github.com/jlowin/fastmcp/tree/main/docs/servers/auth) for full list\n- Meta Tool Discovery, only three tools exposed to client application to preserve context window.\n- Flexible Storage– SQLite (default, zero-config) or PostgreSQL (for scale and production deployments)\n- Stores memories as vectors and allowing memories to be retrieved from natural language queries from AI.\n- Cross Encoder reranking to improve recall and precision of memory retrieval. \n- Flexible ranking (embedding and cross encoder) providers, run everything locally without calls to the cloud thanks to FastEmbed\n- Automatic linking of semantically similar memories, automating the creation of the knowledge graph.\n- 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.\n- 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.\n\nFor the complete roadmap, see [Features Roadmap](docs/features_roadmap.md).\n\n---\n\n## Quick Start\n\n### Option 1: PyPI (Recommended)\n\n```bash\n# Run directly with uvx (no installation needed)\nuvx forgetful-ai\n\n# Or install globally\nuv tool install forgetful-ai\nforgetful\n```\nData stored in platform-appropriate locations (`~/.local/share/forgetful` on Linux/Mac, `AppData` on Windows).\n\nBy default, runs with stdio transport for MCP clients. For HTTP:\n```bash\nuvx forgetful-ai --transport http --port 8020\n```\n\n### Option 2: From Source\n\n```bash\ngit clone https://github.com/ScottRBK/forgetful.git\ncd forgetful\n\n# Install dependencies with uv\nuv sync\n\n# Run the server (uses SQLite by default)\nuv run main.py\n```\nThe server starts with stdio transport. For HTTP: `uv run main.py --transport http`\n\n### Option 3: Docker Deployment (Production/Scale)\n\nForgetful provides two Docker deployment options:\n\n#### SQLite with Docker (Simpler, Single-Container)\n\nSee [docker-compose.sqlite.yml](/docker/docker-compose.sqlite.yml)\n\n```bash\ncd docker\ncp .env.example .env\n# Edit .env: Set DATABASE=SQLite and SQLITE_PATH=data/forgetful.db\ndocker compose -f docker-compose.sqlite.yml up -d\n```\n\nThe SQLite database persists in the `./data` directory on the host.\n\n#### PostgreSQL with Docker (Recommended for multitenant)\n\nSee [docker-compose.postgres.yml](/docker/docker-compose.postgres.yml) and [.env.example](/docker/.env.example)\n\n```bash\ncd docker\ncp .env.example .env\n# Edit .env: Set DATABASE=Postgres and configure POSTGRES_* settings\ndocker compose -f docker-compose.postgres.yml up -d\n```\n\n**Note**: If no `.env` file exists, the application uses defaults from `app/config/settings.py`.\nFor all configuration options, see [Configuration Guide](docs/configuration.md).\n\n### Connecting to An Agent\n\nFor detailed connection guides (Claude Code, Claude Desktop, other clients that support MCP), see [Connectivity Guide](docs/connectivity_guide.md).\n\n- [Claude Code](docs/connectivity_guide.md#claude-code)\n- [VS Code](docs/connectivity_guide.md#vs-code)\n- [Copilot CLI](docs/connectivity_guide.md#copilot-cli) (includes [custom agents and skills](docs/copilot-cli/README.md))\n- [Cursor](docs/connectivity_guide.md#cursor)\n- [Codex](docs/connectivity_guide.md#codex)\n- [Gemini CLI](docs/connectivity_guide.md#gemini-cli) (includes [custom commands](docs/gemini-cli/README.md))\n- [Opencode](docs/connectivity_guide.md#opencode) (includes [custom commands and skills](docs/opencode/README.md))\n\nAdd Forgetful to your MCP client configuration:\n\n**stdio transport (recommended for local use):**\n```json\n{\n  \"mcpServers\": {\n    \"forgetful\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"forgetful-ai\"]\n    }\n  }\n}\n```\n\n**HTTP transport (for Docker/remote):**\n```json\n{\n  \"mcpServers\": {\n    \"forgetful\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8020/mcp\"\n    }\n  }\n}\n```\n\n\n---\n\n## CLI\n\nThe `forgetful` command is also a full terminal client over the same tool registry the\nMCP meta-tools use - against your local database by default, or a remote deployment\nafter `auth login`.\n\n```bash\nuv tool install forgetful-ai\n\n# Curated verbs for daily use\nforgetful memory save \"Set generateResolvConf false to fix WSL2 DNS\" \\\n    --title \"WSL2 DNS fix\" --importance 7\nforgetful memory search \"wsl dns\" -n 5\nforgetful memory get 812\nforgetful memory recent -n 10 -p my-project\nforgetful project list\n\n# Generic passthrough to any of the 42 tools\nforgetful tools list --category memory\nforgetful tools info query_memory\nforgetful call create_project --args '{\"name\": \"Homelab\", \"description\": \"...\", \"project_type\": \"personal\"}'\n\n# Remote deployment (browser OAuth; saves FORGETFUL_SERVER to ~/.config/forgetful/.env)\nforgetful auth login --server https://forgetful.example.com\nforgetful auth status\nforgetful memory search \"wsl dns\"          # now runs against the remote server\nforgetful memory search \"wsl dns\" --local  # force local mode per invocation\n\n# Scripting: --json emits machine-readable output\nforgetful memory search \"wsl dns\" --json | jq '.primary_memories[0].id'\n```\n\n`forgetful serve` is the canonical way to run the MCP server (`forgetful serve\n--transport http --port 8020`); the bare `forgetful` / `uvx forgetful-ai` invocation and\nthe legacy `--transport`/`--re-embed` flags keep working indefinitely, so existing MCP\nclient configurations are unaffected. Headless environments can set `FORGETFUL_TOKEN`\n(bearer) instead of the OAuth flow. See the\n[Configuration Guide](docs/configuration.md#cli-configuration) for precedence rules.\n\n\n---\n\n## Usage Examples\n\nForgetful exposes tools through a **meta-tools pattern** - only 3 tools visible to your MCP client, with 42 tools accessible via `execute_forgetful_tool`. See [Complete Tool Reference](docs/tool_reference.md) for all tools.\n\n### Example 1: Project-Scoped Memory\n\nCreate a memory linked to a project for better organization and scoped retrieval.\n\n```python\n# Create project for organizing related knowledge\nproject = execute_forgetful_tool(\n    \"create_project\",\n    {\n        \"name\": \"E-Commerce Platform Redesign\",\n        \"project_type\": \"work\",\n        \"status\": \"active\"\n    }\n)\n\n# Create memory linked to project\nmemory = execute_forgetful_tool(\n    \"create_memory\",\n    {\n        \"title\": \"Payment gateway: Stripe chosen over PayPal\",\n        \"content\": \"Selected Stripe for better API docs, lower fees, and built-in fraud detection. PayPal lacks webhooks for subscription management.\",\n        \"importance\": 9,\n        \"tags\": [\"payment\", \"stripe\", \"decision\"],\n        \"project_id\": project[\"project_id\"]\n    }\n)\n\n# Later, query within project scope\nresults = execute_forgetful_tool(\n    \"query_memory\",\n    {\n        \"query\": \"payment processing implementation\",\n        \"project_id\": project[\"project_id\"]\n    }\n)\n# Returns: Stripe decision + auto-linked related memories\n```\n\n### Example 2: Knowledge Graph with Entities\n\nTrack people, organizations, and relationships - perfect for team and infrastructure management.\n\n```python\n# New engineer joins your company\nnew_hire = execute_forgetful_tool(\n    \"create_entity\",\n    {\n        \"name\": \"Jordan Taylor\",\n        \"entity_type\": \"Individual\",\n        \"description\": \"Backend Engineer - Payments Team\",\n        \"tags\": [\"engineering\", \"backend\", \"payments\"]\n    }\n)\n\n# Get company entity (create if needed)\ncompany = execute_forgetful_tool(\n    \"create_entity\",\n    {\n        \"name\": \"TechFlow Systems\",\n        \"entity_type\": \"Organization\",\n        \"description\": \"SaaS platform company\"\n    }\n)\n\n# Create employment relationship\nexecute_forgetful_tool(\n    \"create_entity_relationship\",\n    {\n        \"from_entity_id\": new_hire[\"entity_id\"],\n        \"to_entity_id\": company[\"entity_id\"],\n        \"relationship_type\": \"works_for\",\n        \"metadata\": {\n            \"role\": \"Backend Engineer II\",\n            \"department\": \"Payments\",\n            \"start_date\": \"2025-01-20\"\n        }\n    }\n)\n\n# Create memory about hiring\nhire_memory = execute_forgetful_tool(\n    \"create_memory\",\n    {\n        \"title\": \"Jordan Taylor hired - payments focus\",\n        \"content\": \"Jordan joins to build Stripe integration and handle PCI compliance. Previous experience with payment systems at FinanceApp Corp.\",\n        \"importance\": 7,\n        \"tags\": [\"team\", \"hiring\", \"payments\"]\n    }\n)\n\n# Link person to memory\nexecute_forgetful_tool(\n    \"link_entity_to_memory\",\n    {\n        \"entity_id\": new_hire[\"entity_id\"],\n        \"memory_id\": hire_memory[\"memory_id\"]\n    }\n)\n\n# Query Jordan's related knowledge\nresults = execute_forgetful_tool(\n    \"query_memory\",\n    {\"query\": \"Jordan payment implementation\"}\n)\n# Returns: Hiring memory + linked entity + relationship context\n```\n\n### Tool Categories\n\nForgetful provides tools across **7 categories**:\n\n- **Memory Tools** (7) – create, query, update, link, mark obsolete\n- **Project Tools** (5) – organize knowledge by context/scope\n- **Entity Tools** (15) – track people, orgs, devices; build knowledge graphs\n- **Code Artifact Tools** (5) – store reusable code snippets\n- **Document Tools** (5) – store long-form content (\u003e400 words)\n- **Skill Tools** (10) – store procedural knowledge with semantic search and SKILL.md import/export\n- **User Tools** (2) – profile and authentication\n\nFor complete documentation with extensive examples, see [Complete Tool Reference](docs/tool_reference.md).\n\n---\n\n## How It Works\n\n### Atomic Memory Principle\n\nInspired by Zettelkasten, each memory stores **one concept** in ~300-400 words:\n- **Easily titled** – Forces clarity (200 char limit)\n- **Self-contained** – Understandable without external context\n- **Linkable** – Small units enable precise knowledge graphs\n\nFor detailed content, use Documents and extract 3-7 atomic memories that link to the parent document.\n\n### Automatic Knowledge Graph\n\nWhen you create a memory:\n1. **Embedding generated** – FastEmbed converts content to 384-dimensional vector\n2. **Similarity search** – Finds top semantically-related memories (≥0.7 threshold)\n3. **Auto-linking** – Creates bidirectional links to top 3-5 matches (configurable)\n4. **Graph traversal** – Queries return primary results + 1-hop linked memories\n\n### Entities and Knowledge Graphs\n\nEntities represent concrete, real-world things (people, organizations, teams, devices) that can be linked to memories:\n  - **Typed entities** – Organizations, Individuals, Teams, Devices, or custom types\n  - **Relationships** – Directional connections (e.g., \"Person works_at Organization\") with strength and metadata\n  - **Memory linking** – Associate entities with relevant memories for context\n  - **Knowledge graph** – Build networks showing how entities relate to each other and your knowledge base\n\nUse entities for concrete things (Sarah Chen, TechFlow Systems, Cache Server 01) and memories for abstract concepts (architectural patterns, decisions, learnings).\n\n### Token Budget Management\n\nPrevents context window overflow:\n- Configurable budget (default 8K tokens)\n- Results prioritized by importance (9-10 first) → recency (newest first)\n- Truncates gracefully if over budget\n- Respects max memory count (default 20)\n\nThis ensures agents get the most relevant context without overwhelming the LLM.\n\nFor deep dive on search architecture (dense → sparse → RRF → cross-encoder), see [Search Documentation](docs/search.md).\n\n---\n\n## Configuration\n\n**No configuration required** – Forgetful uses sensible defaults out of the box.\n\n### Key Settings (Optional)\n\n- `MEMORY_TOKEN_BUDGET` – Max tokens for query results (default: `8000`)\n- `EMBEDDING_MODEL` – Embedding model (default: `BAAI/bge-small-en-v1.5`)\n- `MEMORY_NUM_AUTO_LINK` – Auto-link count (default: `3`, set `0` to disable)\n- `SERVER_PORT` – HTTP server port (default: `8020`)\n- `MAX_GRAPH_LIMIT` – Upper bound for `/api/v1/graph` `?limit` and `/api/v1/graph/subgraph` `?max_nodes` (default: `2000`)\n\nFor all 40+ environment variables with detailed explanations, see [Configuration Guide](docs/configuration.md).\n\n---\n\n## Documentation\n\n### Guides\n\n- **[Core Concepts](docs/concepts.md)** – Memories vs Entities vs Documents explained\n- **[Complete Tool Reference](docs/tool_reference.md)** – All 42 tools with extensive examples\n- **[REST API Reference](docs/api_reference.md)** – HTTP endpoints for web UI integration\n- [Configuration Guide](docs/configuration.md) – All environment variables explained\n- [Connectivity Guide](docs/connectivity_guide.md) – Connect Claude and other MCP clients\n- [Self-Hosting Guide](docs/self-hosting-guide.md) – Deploy on a VPS with Docker\n- [Search Documentation](docs/search.md) – Embedding pipeline and retrieval architecture\n- [Embedding Migration](docs/embedding_migration.md) – Switch embedding providers safely\n- [Features Roadmap](docs/features_roadmap.md) – Planned features and priorities\n\n### External Resources\n\n- [MCP Protocol Specification](https://modelcontextprotocol.io/) – Model Context Protocol docs\n- [pgvector](https://github.com/pgvector/pgvector) – PostgreSQL vector extension\n- [FastEmbed](https://github.com/qdrant/fastembed) – Local embedding generation\n- [Zettelkasten Principle](https://en.wikipedia.org/wiki/Zettelkasten) – Atomic note-taking method\n\n---\n\n## Contributing\n\nWe welcome contributions! Forgetful uses integration + E2E testing with Docker Compose orchestration.\n\nSee [Contributors Guide](docs/contributors.md) for:\n- Testing workflows (integration tests, E2E tests, GitHub Actions)\n- Development setup (local vs Docker)\n- CI/CD pipeline details\n- Release process\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENCE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FScottRBK%2Fforgetful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FScottRBK%2Fforgetful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FScottRBK%2Fforgetful/lists"}