DOCSEARCHbyAlgolia
Submit Docs

Forgetful AI

repository·main·Indexed 43 days ago

https://github.com/scottrbk/forgetful

An MCP (Model Context Protocol) server providing AI agents with persistent, shared, and semantically-searchable memory based on the Zettelkasten principle. It integrates with GitHub Copilot CLI, Gemini CLI, and OpenCode to offer atomic knowledge management, knowledge graph traversal, and repository bootstrapping.

Tokens
85.9K
Snippets
204
Records
338
Agent score
55%

What's inside Forgetful

  1. File binary content into Forgetful

    main

    Use the forgetful-files skill to store binary artifacts like screenshots, PDFs, diagrams, fonts, or assets alongside your knowledge base. This is useful when a binary artifact is worth keeping with knowledge or when a stored procedure requires a bundled asset.

    Note on availability: File operations are feature-flagged. If discovery does not list them, the server has FILES_ENABLED set to off.

  2. What is Forgetful and how does it work?

    main

    Forgetful is a storage and retrieval tool for AI Agents, implemented as a Model Context Protocol (MCP) server. It provides a shared knowledge base that allows different agents (e.g., Claude Code, Copilot, custom bots) to persist and retrieve context.

    Core Philosophy: The Zettelkasten Principle

    Unlike other memory services, Forgetful is opinionated about how data is stored. It enforces the Zettelkasten principle, requiring that each memory is atomic (one concept per note).

    When an agent records a memory, Forgetful requires:

    1. Title and Content
    2. Context (what the agent was doing)
    3. Keywords and Tags

    Key Mechanisms

    • Semantic Embeddings: Uses vector storage and semantic search to allow retrieval via natural language.
    • Automatic Linking: Automatically links new memories to existing ones based on similarity scores, building an evolving knowledge graph (similar to Obsidian for AI).
    • Reranking: Uses Cross-Encoder reranking to improve the precision and recall of retrieved information.
    • Multi-Agent Coordination: Supports Plans and Tasks with acceptance criteria, state management (optimistic locking), and dependency tracking (cycle detection).
    • Procedural Memory: Supports Skills (following the Agent Skills standard) to store step-by-step instructions that can be cross-referenced with memories.

  3. Distinguish between Entities, Memories, and Documents

    main

    The Forgetful system uses three distinct abstractions to organize knowledge. Choosing the right one is critical for effective retrieval:

    • Entities: Represent concrete things like people, organizations, teams, or devices. Use create_entity for these.
    • Memories: Represent abstract knowledge, such as decisions, patterns, or learnings. These should be atomic.
    • Documents: Used for full-context storage of long-form content or detailed analysis. Memories should act as atomic summaries that link to these documents to facilitate search surfacing.

  5. Distinguish between Skills and Memories

    main

    Use this distinction to separate procedural knowledge from declarative knowledge:

    • Skill: Procedural and reusable. It contains the steps or instructions on how to do something.
    • Memory: Declarative. It contains facts or decisions about what something is.

    Examples:

    • "How to review pull requests in this project" $\rightarrow$ Skill
    • "We use conventional commits for all PRs" $\rightarrow$ Memory

  6. Understand User Provisioning from Auth Tokens

    main

    When authentication is enabled, Forgetful automatically provisions users in the database based on claims found in the provided token.

    Required Claims:

    • sub: Subject identifier (maps to external_id).
    • name OR preferred_username: Used for the display name.

    Optional Claims:

    • email: Used for the user's email address.

    Lifecycle:

    • First request: The user is created in the database.
    • Subsequent requests: The user is retrieved via their external_id.
    • Updates: The user's name and email are updated automatically if they change in the token.
    {
  "sub": "auth0|507f1f77bcf86cd7994311",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "iat": 1700000000,
  "exp": 1700003600
}

  7. Characteristics of Forgetful prompts

    main

    All Forgetful prompts share these core traits:

    • Project-agnostic: Reusable across different codebases.
    • Agent-optimized: Provide direct, executable instructions and concrete tool calls (e.g., query_memory, create_memory, update_memory, discover_forgetful_tools) with specific parameters.
    • Action-oriented: Organized into phases without human time constraints.

    Specific Prompt Details

    Rapid Scan

    • 3 phases: Foundation $\rightarrow$ Architecture $\rightarrow$ Context.
    • Uses parallel file reads and strategic sampling (80/20 rule) rather than exhaustive reading.

    Comprehensive Understanding

    • 4 phases: KB Mining $\rightarrow$ Code Exploration $\rightarrow$ Synthesis $\rightarrow$ Documentation.
    • Focuses on deep pattern identification, dependency mapping, and extracting the rationale (the 'why') behind code, not just the 'what'.

    KB Bootstrap

    • Includes Phase 0: Discovery & Assessment to prevent duplicates via gap analysis.
    • Follows 10 phases: Project $\rightarrow$ Architecture $\rightarrow$ Patterns $\rightarrow$ Features $\rightarrow$ Decisions $\rightarrow$ Config $\rightarrow$ Artifacts $\rightarrow$ Documents $\rightarrow$ Entities $\rightarrow$ Linking.
    • Targets coverage of 15-25 memories, 5-10 artifacts, and 3-5 documents.

  8. Follow Atomic Memory Principles for high-quality knowledge

    main

    When creating memories for the knowledge base, follow these principles to ensure they are useful for semantic search and LLM retrieval:

    Do:

    • One concept per memory: Avoid "mega-memories" that combine unrelated topics.
    • Ideal length: Aim for 200-400 words. If a topic exceeds 2000 characters, use a linked document instead.
    • Self-contained: Ensure the memory is understandable on its own without assuming external context.
    • Include context: Always use the context field to explain the memory's relevance.
    • Honest scoring: Use importance scores accurately (roughly 70% of memories should be scored 7-8).

    Don't:

    • Combine multiple unrelated concepts.
    • Exceed 2000 characters per memory.
    • Assume the reader has existing context.
    • Inflate importance scores.

  9. Understand the nine building blocks of Forgetful

    main

    Forgetful organizes knowledge into nine distinct building blocks. Choosing the correct type ensures your knowledge graph remains searchable and structured rather than becoming a cluttered dump.

    The Building Blocks

    1. Memories: Atomic knowledge units (one concept per note). These are the only directly queryable type. Documents and Code Artifacts must be linked to memories to be discoverable.
    2. Entities: Real-world things like people, organizations, devices, or products. They represent concrete nouns and can have relationships with each other or with memories.
    3. Plans: Containers for structured work (goals and context). Plans decompose goals into tasks and follow a lifecycle: draft → active → completed → archived.
    4. Tasks: Actionable work units within a plan. They use a state machine (todo → doing → done, plus waiting and cancelled) and support priority levels (P0-P3) and optimistic locking for concurrent agent access.
    5. Acceptance Criteria: Boolean, verifiable conditions attached to tasks. All criteria must be met before a task can transition to done.
    6. Documents: Long-form reference material (>300 words). Best practice is to create a document and then extract 3-7 atomic memories that link back to it for better searchability.
    7. Code Artifacts: Reusable code snippets or patterns attached to memories.
    8. Skills: Procedural, step-by-step instructions (the "HOW" vs the "WHAT"). They follow the Agent Skills standard and are portable via SKILL.md files.
    9. Projects: Organizational scopes used to group memories and filter queries by context.

    Decision Flow Summary

    QuestionAnswer
    Is it a person, org, device, or product?Entity
    Is it a goal that decomposes into steps?Plan
    Is it a concrete piece of work to be done?Task
    Is it a verifiable condition for "done"?Acceptance Criterion
    Is it step-by-step procedural knowledge?Skill
    Is it detailed analysis or a guide (>300 words)?Document
    Is it a single fact, decision, or preference?Memory
    Is it reusable code?Code Artifact
    Does it help scope/filter other knowledge?Project

  10. Best practices for creating and searching skills

    main

    Forgetful's skill store is designed for procedural memory (how-tos) rather than facts (memories). Follow these steps to manage skills effectively:

    1. Apply the Litmus Test

    Determine if the information is a skill or a memory.

    • Skill: A procedure with steps that someone follows in order (e.g., "How to review pull requests").
    • Memory: A fact that is recalled and applied (e.g., "We use conventional commits"). Use forgetful-remember for facts.

    2. Search Before Creating

    Always run search_skills before creating a new skill to avoid duplication.

    • Semantic Search: Search is semantic over skill descriptions, not names.
    • Query Strategy: Query by what the procedure achieves (e.g., "rotate credentials") rather than the exact name of the skill.
    • Update vs. Create: If an existing skill covers the capability, use update_skill instead of create_skill. Skill names must be unique.

    3. Optimize the Description for Retrieval

    In Forgetful, the description is the primary retrieval surface. While the content (up to 100KB) is stored, it is not searched semantically.

    • Write for Search: The description should explicitly state what the procedure achieves, when to use it, and include capability keywords.
    • Structure: Use a kebab-case name, the full markdown procedure as content, relevant tags, and an importance level when calling create_skill.

  11. Distinguish between Memories and Documents

    main

    Use this distinction to manage the granularity of your knowledge base:

    • Memory: Represents a single concept. It should be scannable and typically contains <400 words.
    • Document: Represents multiple related concepts or reference material. It typically contains >300 words.

    Workflow Tip: When you have a large Document, you should extract atomic Memories from it to ensure they are easily searchable and usable by agents.

  12. Manage procedural knowledge with Skill Tools

    main

    Forgetful provides a suite of tools to store and manage procedural knowledge (step-by-step instructions, agent capabilities) following the Agent Skills open standard. Skills are stored as markdown content and can be semantically searched, imported from SKILL.md files, or exported back to markdown format. They can also be bidirectionally linked to specific memories.

    # Example of creating a skill
skill = execute_forgetful_tool(
    "create_skill",
    {
        "name": "code-review",
        "description": "Systematic code review process for pull requests",
        "content": "# Code Review\n\n## Steps\n1. Check for breaking changes...",
        "tags": ["development", "review", "quality"],
        "importance": 8
    }
)