using-forgetful-memory

What this skill does

# Using Forgetful Memory

Forgetful is a semantic memory system using Zettelkasten (atomic note) principles. This skill guides effective memory usage.

## When to Query Memory

Query memory proactively when:
- Starting work on a project (check for existing context)
- User references past work, decisions, or discussions
- Encountering a problem that may have been solved before
- Implementing patterns that may already be documented
- Needing context about preferences or approaches

Use `execute_forgetful_tool("query_memory", {...})` with:
- `query`: Natural language search terms
- `query_context`: Why you're searching (improves ranking)
- `include_links`: true (to see connected knowledge)

### Getting Recent Memories for a Project

To see what's been recorded recently for a specific project:

```
execute_forgetful_tool("get_recent_memories", {
  "limit": 10,
  "project_ids": [PROJECT_ID]
})
```

This is useful when:
- Starting a session on a project you haven't worked on recently
- Reviewing what was captured in previous conversations
- Getting a quick overview of project knowledge

## When to Create Memory

Create memories for knowledge worth preserving:
- Important decisions with rationale (importance 8-9)
- Technical patterns or approaches (importance 7-8)
- Architectural choices (importance 9-10)
- Preferences and workflows (importance 8-9)
- Project milestones (importance 6-7)
- Solutions to non-trivial problems (importance 7-8)

Do NOT create memories for:
- Temporary context (current file paths, transient issues)
- Common knowledge available elsewhere
- Trivial or throwaway information
- Content that changes frequently

## Atomic Memory Principles

Each memory must pass the atomicity test:
1. Can you understand it at first glance?
2. Can you title it in 5-50 words?
3. Does it represent ONE concept/fact/decision?

### Constraints

| Field | Limit | Guidance |
|-------|-------|----------|
| Title | 200 chars | Short, searchable phrase |
| Content | 2000 chars | Single concept (~300-400 words) |
| Context | 500 chars | WHY this matters |
| Keywords | 10 max | For semantic clustering |
| Tags | 10 max | For categorization |

### Importance Scoring

| Score | Use For |
|-------|---------|
| 9-10 | Personal facts, foundational patterns |
| 8-9 | Critical solutions, major decisions |
| 7-8 | Useful patterns, preferences |
| 6-7 | Milestones, specific solutions |
| 5-6 | Minor context (use sparingly) |

## Project Discovery

Before creating memories, find the correct project:

1. **Get current repo** - Check the git remote:
   ```bash
   git remote get-url origin
   ```
   Extract the repo identifier (e.g., `ScottRBK/forgetful-plugin`)

2. **Search by repo** - Filter projects directly:
   ```
   execute_forgetful_tool("list_projects", {"repo_name": "owner/repo"})
   ```

3. **Use the project_id** - Never assume project 1 - always discover first

If no project exists for the current repo:
- Ask user if they want to create one (with `repo_name` set)
- Or scope the memory without a project_id (global memory)

## Query Before Create

Always check for existing memories before creating:

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

If similar memory exists:
- Update it instead of creating duplicate
- Or mark it obsolete if superseded
- Or link new memory to existing one

## Announcing Memory Operations

When creating a memory (importance >= 7), announce:
```
💾 Saved to memory: "[title]"
   Tags: [tags]
   Related: [auto-linked memory titles]
```

When querying, summarize:
```
Found X memories about [topic]:
- [Memory 1]: [brief insight]
- [Memory 2]: [brief insight]
```

## Content That's Too Long

If content exceeds 2000 chars:
1. Use `create_document` for full content
2. Extract 3-5 atomic memories as entry points
3. Link memories to document via `document_ids`

Example: Architecture overview (document) → separate memories for each layer/decision.

---

## Tool Quick Reference

Common tools you can call directly via `execute_forgetful_tool(tool_name, args)`:

### Memory Tools
| Tool | Required Params | Description |
|------|-----------------|-------------|
| `query_memory` | `query`, `query_context` | Semantic search |
| `create_memory` | `title`, `content`, `context`, `keywords`, `tags`, `importance` | Store atomic memory |
| `get_memory` | `memory_id` | Get full memory details |
| `update_memory` | `memory_id` | PATCH update fields |
| `link_memories` | `memory_id`, `related_ids` | Manual bidirectional linking |
| `mark_memory_obsolete` | `memory_id`, `reason` | Soft delete with audit |
| `get_recent_memories` | (none) | Recent memories list |

### Project Tools
| Tool | Required Params | Description |
|------|-----------------|-------------|
| `list_projects` | (none) | List all projects |
| `create_project` | `name`, `description`, `project_type` | Create project container |
| `get_project` | `project_id` | Get project details |

### Entity Tools
| Tool | Required Params | Description |
|------|-----------------|-------------|
| `create_entity` | `name`, `entity_type` | Create org/person/device |
| `search_entities` | `query` | Text search by name/aka |
| `link_entity_to_memory` | `entity_id`, `memory_id` | Link entity↔memory |
| `get_entity_memories` | `entity_id` | All memories for entity |
| `create_entity_relationship` | `source_entity_id`, `target_entity_id`, `relationship_type` | Knowledge graph edge |

### Document & Code Artifact Tools
| Tool | Required Params | Description |
|------|-----------------|-------------|
| `create_document` | `title`, `description`, `content` | Long-form content |
| `create_code_artifact` | `title`, `description`, `code`, `language` | Reusable code |

**Full schemas**: See [TOOL_REFERENCE.md](TOOL_REFERENCE.md) for complete parameter details and examples.