Very cool project, could you clarify some concepts

[CharlieBytesX]

Hi, im really new to the mcp world
In the examples I see the tools called directly

When I add the mcp to agents (cursor, gemini cli, ...)
Do i need to call the tools myself in some way? Or the agent is the one who always call the tools, if the agent is the one who call them. What would be a good approach to use in the prompts.

1. When i just open agent and want to code for the first time
2. When i just open the agent and want to code, after step one so forgetull alreay have some info of the project

I didn't understand the example of Readme because it shows the tools being called, but now chat words or Rules to add to the agent so it uses forgetfull in the best way

Thanks

[ScottRBK]

Hey @CharlieBytesX

Have a look at the Claude Code Plugin for Forgetful Commands. I'd reocmmend in whatever coding agent you are using, trying to set up similar repeatable commands, Commands in Cursor for example.

I will set about creating example documentation for this in the README.md as well in the comming days.

These are often the best way to go about using the tool, I have given what I think is quite a common workflow with the tool, saving and adding memories, but I intend to extend this out, likely with the help of others using the tool in ways that I had no envisaged or have yet to come across. It is fairly open ended and designed to be used in many use cases (I give a lot of examples of using it with coding agents but I intend also use it with general purpose agents such as claude desktop and chatgpt, and even those that I build myself).

In addition to this, if you just give the agent natural language instructions to 'save this to forgetful' or 'can you check forgetful for x' then that also works, but i like to try wrap it in those commands as it gets the agent to do things like check for existing entries, or when exploring the knowledge base to use a sub agent to protect its context window (need to be careful with sub agents as I suspect some coding agents don't support them).

Hope this helps, let me know if you have any further questions and thanks for checking out the tool :).

[CharlieBytesX]

Thanks!! Now it makes much more sense

I just added as commands to gemini cli and encode-repo works great!!
Let me know if you want the claude commands in the gemini format (I just used gemini itself to create them so you can generate the same way if you want)

[ScottRBK]

Oh yes, please send them on and i will add them to the docs. Thanks for that @CharlieBytesX

[CharlieBytesX]

Sure:

Based on gemini custom comands:
docs

Under ~/.gemini/commands

Add this files:

Unified Commands

encode-repo.toml

description = "Bootstrap a repository into Forgetful's knowledge base"
prompt = """
# Encode Repository

Systematically populate the Forgetful knowledge base with comprehensive project context using the Zettelkasten-inspired bootstrap protocol.

## Purpose

Transform an undocumented or lightly-documented codebase into a rich, searchable knowledge repository. Use this when:
- Starting to use Forgetful for an existing project
- Onboarding a new project into the memory system
- Preparing a project for AI agent collaboration
- Creating institutional knowledge for team members

## Arguments

{{args}}

Parse for:
- **Project path**: Directory to encode (default: current working directory)
- **Project name**: Override auto-detected name (optional)
- **Phases**: Specific phases to run (optional, default: all)

---

## Phase 0: Discovery & Assessment (ALWAYS START HERE)

### Step 1: Check for Existing Project

```
execute_forgetful_tool("list_projects", {})
```

Search for the project. If found:
- Note the `project_id` (required for linking)
- Review description, project_type, status
- Check notes field for operational details

### Step 2: Assess Project Size & Scope

Explore the codebase to determine:

**Project Size:**
- Lines of code: Small <5K, Medium 5K-50K, Large >50K
- File count: Small <50, Medium 50-500, Large >500

**Project Type:**
- Simple app/script
- Standard web app
- Library/SDK
- Microservice
- Monorepo
- Integration/ETL

### Step 3: Query Existing KB Coverage

```
execute_forgetful_tool("query_memory", {
  "query": "<project-name> architecture overview",
  "query_context": "Assessing existing knowledge base coverage for bootstrap",
  "k": 10,
  "include_links": true,
  "project_ids": [<project_id if exists>]
})
```

### Step 4: Analyze Current Codebase

Read key files:
- README.md
- pyproject.toml / package.json / Cargo.toml
- Main entry points
- Configuration files

### Step 5: Gap Analysis

Compare KB vs Codebase:
- What's documented and current?
- What's documented but outdated?
- What's missing from KB?
- What memories reference non-existent code?

Report gap analysis before proceeding.

---

## Memory Targets by Project Profile

| Profile | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | Total |
|---------|---------|---------|---------|---------|---------|-------|
| Small Simple | 3-5 | 3-5 | 3-5 | 2-4 | 2-3 | 15-27 |
| Small Complex | 5-7 | 5-8 | 5-8 | 4-6 | 3-5 | 26-42 |
| Medium Standard | 5-10 | 10-15 | 8-12 | 5-10 | 5-8 | 35-60 |
| Large | 8-12 | 15-20 | 12-18 | 10-15 | 8-12 | 60-100 |

---

## Phase 1: Project Foundation (5-10 memories)

### Create/Update Project Entity

If project doesn't exist:
```
execute_forgetful_tool("create_project", {
  "name": "owner/repo-name",
  "description": "<2-3 paragraphs: problem solved, features, tech stack>",
  "project_type": "development",
  "repo_name": "owner/repo",
  "notes": "<operational details: how to run, test, deploy>"
})
```

### Create Foundation Memories

1. **Project Overview** (Importance: 10)
   - Problem solved, users, unique value, status

2. **Technology Stack** (Importance: 9)
   - Language, frameworks, critical dependencies

3. **Architecture Pattern** (Importance: 10)
   - Style, major components, data flow

4. **Development Setup** (Importance: 8)
   - Prerequisites, install steps, configuration

5. **Testing Strategy** (Importance: 8)
   - Frameworks, categories, commands

---

## Phase 2: Architectural Deep Dive (10-15 memories)

One memory per major architectural layer:
- Routes/Controllers
- Service/Business Logic
- Repository/Data Access
- Models/Domain Entities
- Middleware
- Authentication
- Configuration

Template:
```
{
  "title": "[Project] - [Layer] Layer Implementation",
  "content": "Purpose, location, patterns used, interactions, design decisions",
  "context": "Understanding this layer for [specific tasks]",
  "keywords": ["layer-name", "pattern", "directory"],
  "tags": ["architecture", "layer"],
  "importance": 8,
  "project_ids": [<project_id>]
}
```

---

## Phase 3: Key Patterns & Practices (8-12 memories)

Document recurring patterns:
- Dependency injection
- Error handling
- Database transactions
- Async patterns
- Validation
- Caching
- Event handling

---

## Phase 4: Critical Features (1-2 per feature)

For each major feature:
```
{
  "title": "[Project] - [Feature] Implementation",
  "content": "User perspective, technical approach, key files, data flow",
  "context": "Critical feature that [business value]",
  "importance": 8,
  "tags": ["feature", "implementation"]
}
```

---

## Phase 5: Design Decisions (ONLY from explicit documentation)

**CRITICAL: Only capture decisions that are explicitly documented in the repository.**

### Where to Look for Documented Decisions

Search for explicit decision documentation:
- `docs/adr/` or `docs/decisions/` (Architecture Decision Records)
- `DECISIONS.md` or `ARCHITECTURE.md`
- README sections titled "Why", "Design", "Architecture Decisions"
- Code comments with `DECISION:`, `RATIONALE:`, or `WHY:`
- Commit messages or PR descriptions with explicit rationale
- `docs/*.md` files with decision context

### What NOT to Do

- Do NOT infer or guess at design rationales
- Do NOT create decision memories based on code patterns alone
- Do NOT assume "they probably chose X because Y"
- If rationale is not explicitly documented, do NOT create a decision memory

### Process

1. Search for ADR files:
   ```
   Glob: **/adr/**/*.md, **/decisions/**/*.md
   Grep: "Decision:", "Rationale:", "Context:", "## Why"
   ```

2. For each documented decision found, create memory:
   ```
   {
     "title": "[Project] - Decision: [Topic]",
     "content": "<QUOTE or PARAPHRASE the documented rationale>",
     "context": "Documented in [file path]",
     "importance": 9,
     "tags": ["decision", "documented"]
   }
   ```

3. If no explicit decision documentation exists:
   - Report: "No explicit decision documentation found in repository"
   - Skip this phase
   - Optionally suggest the user document key decisions

### Template for Documented Decisions
```
{
  "title": "[Project] - Decision: [Topic]",
  "content": "Decision: [what was decided]. Rationale: [quoted/paraphrased from docs]. Alternatives considered: [if documented]. Source: [file path]",
  "context": "Documented decision from [source file]",
  "importance": 9,
  "tags": ["decision", "documented", "architecture"]
}
```

---

## Phase 6: Code Artifacts (as needed)

For reusable code patterns, use:
```
execute_forgetful_tool("create_code_artifact", {
  "title": "Descriptive name",
  "description": "What it does, when to use",
  "code": "<implementation>",
  "language": "python",
  "tags": ["middleware", "pattern"],
  "project_id": <project_id>
})
```

Then link to memories via `code_artifact_ids`.

---

## Phase 7: Documents (as needed)

For content >400 words:
```
execute_forgetful_tool("create_document", {
  "title": "Document name",
  "description": "Overview and purpose",
  "content": "<full documentation>",
  "document_type": "markdown",
  "project_id": <project_id>
})
```

Create 3-5 atomic memories as entry points, linked via `document_ids`.

---

## Execution Guidelines

1. **Execute phases in order**: 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7
2. **Skip phases** with good existing coverage (from gap analysis)
3. **Update outdated memories** as discovered
4. **Mark obsolete** memories that reference removed code
5. **Link new memories** to existing related memories

## Quality Principles

- **One concept per memory** (atomic)
- **200-400 words ideal** per memory
- **Include context field** explaining relevance
- **Honest importance scoring** (most should be 7-8)
- **Quality over quantity**
- **Only document what's explicitly in the repo** (especially for decisions)

---

## Validation

After completion, test with queries:
```
execute_forgetful_tool("query_memory", {
  "query": "How do I add a new API endpoint?",
  "query_context": "Testing bootstrap coverage",
  "project_ids": [<project_id>]
})
```

If searches return poor results, create additional memories in those areas.

---

## Report Progress

After each phase, report:
- Memories created/updated
- Gaps remaining
- Suggested next steps

Ask user to confirm before proceeding to next phase.
"""

forgetful-setup.toml

description = "Configure Forgetful MCP server for Claude Code"
prompt = """
# Forgetful Setup

Configure the Forgetful semantic memory MCP server.

## Step 1: Check Existing Configuration

First, check if Forgetful is already configured:

```bash
claude mcp list | grep -i forgetful
```

If already configured:
- Ask user if they want to reconfigure
- If no, exit with message: "Forgetful is already configured. Use `claude mcp list` to see details."
- If yes, remove existing first: `claude mcp remove forgetful`

## Step 2: Choose Setup Type

Ask the user which setup they prefer:

**Question**: "How would you like to configure Forgetful?"

**Options**:
1. **Standard (Recommended)** - Zero config, uses uvx to run Forgetful with SQLite storage. Perfect for most users.
2. **Custom** - For advanced setups: remote HTTP server, PostgreSQL, custom embeddings, authentication, etc.

## Step 3a: Standard Setup

If user chose Standard:

```bash
claude mcp add forgetful --scope user -- uvx forgetful-ai
```

Confirm success:
```bash
claude mcp list | grep -i forgetful
```

Report: "Forgetful is now configured! Your memories will persist in `~/.forgetful/` using SQLite."

## Step 3b: Custom Setup

If user chose Custom:

1. Fetch the configuration docs:
```
WebFetch: https://github.com/ScottRBK/forgetful/blob/main/docs/configuration.md
```

2. Ask what they need:
   - **Remote HTTP server** - Connect to Forgetful running elsewhere
   - **PostgreSQL backend** - Use Postgres instead of SQLite
   - **Custom embeddings** - Use different embedding model/provider
   - **Authentication** - API key or OAuth setup

3. Based on their answers, guide them through the relevant configuration options from the docs.

4. Build the appropriate command:

**For HTTP remote server:**
```bash
claude mcp add forgetful --scope user --transport http http://HOST:PORT/mcp
```

**For stdio with environment variables:**
```bash
claude mcp add forgetful --scope user -e VAR1=value1 -e VAR2=value2 -- uvx forgetful-ai
```

5. Test the configuration:
```bash
claude mcp list | grep -i forgetful
```

## Troubleshooting

If setup fails:
- Check if `uvx` is installed: `which uvx`
- For HTTP: verify the server is running and accessible
- Check Claude Code logs for MCP connection errors

## Notes

- Configuration is stored in `~/.claude.json` and persists across plugin updates
- SQLite database location: `~/.forgetful/forgetful.db`
- For full configuration reference: https://github.com/ScottRBK/forgetful/blob/main/docs/configuration.md
"""

memory-explore.toml

description = "Deep exploration of the Forgetful knowledge graph"
prompt = """
# Memory Explore

Perform deep knowledge graph traversal using a lightweight subagent.

**Query**: {{args}}

Use the Task tool to launch a subagent:

```
Task({
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Explore Forgetful graph",
  prompt: <see below>
})
```

## Subagent Prompt

Use this prompt, substituting the user's query:

```
Explore the Forgetful knowledge graph for: "{user query}"

## Exploration Strategy
- Explore DEEPLY - follow links aggressively, expand entities, traverse relationships
- Be thorough - token cost is acceptable for comprehensive exploration
- Track visited IDs to prevent cycles
- But only SURFACE results relevant to the user's query in your final response
- Filter out tangential discoveries - the main agent only needs focused, relevant context

Execute these phases sequentially:

**Phase 1 - Semantic Entry:**
execute_forgetful_tool("query_memory", {
  "query": "{user query}",
  "query_context": "Deep exploration via /memory-explore command",
  "k": 5,
  "include_links": true,
  "max_links_per_primary": 5
})

Collect all primary_memories and linked_memories.

**Phase 2 - Expand Memory Details:**
For each primary memory, call:
execute_forgetful_tool("get_memory", {"memory_id": <id>})

Extract: document_ids, code_artifact_ids, project_ids, linked_memory_ids

**Phase 3 - Entity Discovery:**
For discovered project_ids, call:
execute_forgetful_tool("list_entities", {"project_ids": [<ids>]})

**Phase 4 - Entity Relationships:**
For each relevant entity, call:
execute_forgetful_tool("get_entity_relationships", {
  "entity_id": <id>,
  "direction": "both"
})

**Phase 5 - Entity-Linked Memories:**
For each entity, call:
execute_forgetful_tool("get_entity_memories", {"entity_id": <id>})

Fetch any new memories not already visited.

---

**IMPORTANT: Filter and summarize before returning.**
You may have explored dozens of nodes - only include those RELEVANT to "{user query}".
Return a structured summary:

## Memories Found
**Primary (N):**
- [Title] (importance: X) - brief content snippet...

**Linked (N):**
- [Title] (importance: X) - connection type...

**Entity-linked (N):**
- [Title] - discovered via [Entity Name]...

## Entities Discovered
- [Name] (type) - X relationships, Y linked memories

## Documents & Artifacts
- [Title] (type/language) - if any found

## Graph Summary
- Total: X memories, Y entities, Z documents/artifacts
- Key themes: [identified clusters]
- Suggested follow-up: /memory-explore "[related query]"
```

## After Subagent Returns

Present the knowledge graph summary to the user. The subagent has done the heavy lifting - you just need to display its findings.

If the graph is sparse, suggest:
- Broader search terms
- Different project scope
- Creating new memories to build the graph
"""

memory-list.toml

description = "List recent memories from Forgetful"
prompt = """
# List Recent Memories

Show the most recently created memories from Forgetful.

## Your Task

Retrieve recent memories using `execute_forgetful_tool("get_recent_memories", {...})`.

**Arguments**: {{args}}

## Parameters

Parse the arguments for:
- **Number**: If user specifies a count (e.g., "10", "last 5"), use that as `limit`
- **Project**: If user mentions a project name, first list projects to get the ID, then filter

Default: `{"limit": 10}`

## Response Format

Present memories in a clean, scannable format:

```
Recent Memories (showing X of Y):

1. [Title] (Importance: X, Created: date)
   Tags: [tags]

2. [Title] (Importance: X, Created: date)
   Tags: [tags]

...
```

## Optional Enhancements

If the user asks for more detail on any memory, use `get_memory` to retrieve full content.

If filtering by project and no project_id provided, first call:
```
execute_forgetful_tool("list_projects", {})
```
Then let the user select or infer from context.

## Examples

**Basic usage:**
```
/memory-list
```
Returns last 10 memories across all projects.

**With count:**
```
/memory-list 5
```
Returns last 5 memories.

**With project filter:**
```
/memory-list forgetful project
```
Lists projects, finds "forgetful" project ID, returns recent memories for that project.
"""

memory-save.toml

description = "Save current context as an atomic memory in Forgetful"
prompt = """
# Save Memory

Create an atomic memory from the current conversation context.

## Your Task

1. Analyze the conversation for the key insight/decision/pattern to capture
2. Check for existing related memories that might be affected
3. Create the memory with proper curation

**User guidance**: {{args}}

## Pre-Creation: Check for Existing Memories

Before creating, query for related memories:
```
execute_forgetful_tool("query_memory", {
  "query": "<topic of new memory>",
  "query_context": "Checking for existing memories before creating new one",
  "k": 5,
  "include_links": true
})
```

Analyze results to determine if the new memory would:
- **Invalidate** an existing memory (mark it obsolete with `mark_memory_obsolete`)
- **Update** an existing memory (use `update_memory` instead of creating new)
- **Supersede** an existing memory (create new, then mark old as obsolete with `superseded_by`)
- **Complement** existing memories (create new and potentially `link_memories`)

## Atomic Memory Principles (Zettelkasten)

Before creating, verify the memory passes the atomicity test:
- Can you understand the idea at first glance?
- Can you easily title it in 5-50 words?
- Does it represent ONE concept/fact/decision?

## Memory Constraints

- **Title**: Max 200 characters - short, searchable phrase
- **Content**: Max 2000 characters (~300-400 words) - single concept
- **Context**: Max 500 characters - WHY this matters
- **Keywords**: Max 10 - for semantic clustering
- **Tags**: Max 10 - for categorization

## Importance Scoring Guide

- **9-10**: Personal facts, foundational architectural patterns
- **8-9**: Critical technical solutions, major architectural decisions
- **7-8**: Useful patterns, strong preferences, tool choices
- **6-7**: Project milestones, specific solutions
- **5-6**: Minor context (use sparingly)

## Process

1. **Query** existing memories on the topic
2. **Analyze** if this is new knowledge, an update, or supersedes existing
3. **Draft** a memory following atomic principles
4. **Present** the draft with curation plan:
   ```
   Existing memories found:
   - Memory #42: "Previous auth decision" - will be marked obsolete (superseded)

   Ready to save this memory:

   Title: [proposed title]
   Content: [proposed content]
   Context: [why this matters]
   Keywords: [keyword1, keyword2, ...]
   Tags: [tag1, tag2, ...]
   Importance: [score with reasoning]
   Project: [if applicable]

   Curation actions:
   - Mark #42 obsolete (superseded by new memory)
   - Link to #38 (related pattern)

   Confirm? (y/n/edit)
   ```
5. **Execute** the curation plan after user confirms
6. **Report** the result including any auto-linked memories

## If Content is Too Long

If the concept requires >2000 characters:
1. Suggest using `create_document` for the full content
2. Extract 3-5 atomic memories from it
3. Link memories to the document via `document_ids`

## Example with Curation

User: `/memory-save`

You query existing memories, find related content, and propose:
```
Found 2 related memories:
- #89: "Plugin strategy: single plugin" (Importance: 7) - OUTDATED by this decision
- #45: "MCP scope hierarchy" (Importance: 8) - Related context

Ready to save this memory:

Title: "Plugin architecture: Two-plugin strategy (forgetful + context-hub)"
Content: "Decided on two-plugin approach: (1) forgetful - standalone memory tools,
(2) context-hub - orchestrates Forgetful + Context7 + WebSearch. Claude Code handles
duplicate MCP configs gracefully via scope hierarchy."
Context: "Architecture decision for shipping Forgetful as a Claude Code plugin"
Keywords: [claude-code, plugin, forgetful, mcp, architecture]
Tags: [decision, architecture]
Importance: 8 (major architectural decision)
Project: My Project (ID: 1)

Curation actions:
- Mark #89 obsolete (superseded by new memory)
- Link to #45 (MCP scope hierarchy context)

Confirm? (y/n/edit)
```
"""

memory-search.toml

description = "Search memories semantically using Forgetful"
prompt = """
# Memory Search

Search the Forgetful knowledge base for relevant memories.

## Your Task

Perform a semantic search using `execute_forgetful_tool("query_memory", {...})` with the user's query.

**Query**: {{args}}

## Search Parameters

Use these parameters for the search:

```
{
  "query": "<user's search query>",
  "query_context": "User initiated search via /memory-search command",
  "k": 5,
  "include_links": true,
  "max_links_per_primary": 3
}
```

If the query mentions a specific project, add `project_ids` filter.

## Response Format

Present results clearly:

1. **Summary**: Brief overview of what was found (or "No relevant memories found")
2. **Primary Memories**: For each memory show:
   - Title (with importance score)
   - Key content snippet
   - Tags
   - Linked memories if relevant
3. **Suggestions**: If results seem incomplete, suggest refining the query or creating a new memory

## Example

User: `/memory-search authentication patterns`

You search and respond:
```
Found 3 memories about authentication patterns:

1. **FastAPI JWT Authentication** (Importance: 9)
   JWT middleware using httponly cookies for security...
   Tags: security, authentication, fastapi

2. **OAuth2 Decision** (Importance: 8)
   Chose OAuth2 over API keys for user-facing auth...
   Tags: decision, oauth, security

Related: Memory #45 (Session management approach)
```
"""

[ScottRBK]

Now in 503feb6 - thanks for the help on this @CharlieBytesX