agentleFS
ScottRBKScottRBK/forgetful/skills/forgetful-remember/SKILL.md

forgetful-remember

Skill341 starsChanged 23 days agoMITView on GitHub

Remember knowledge worth keeping — a decision made, a solution found, a preference stated, a pattern confirmed. Use when work surfaces something future sessions will need, or the user asks to remember something. Routes content to the right store (memory, document, code artifact, entity, procedure, file) and enforces query-before-create.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every write needs a deliberate project decision.

    line 51
  2. Very specific:

    Search for overlapping knowledge using the candidate's own essence as the query (query_memory with query and query_context).

    line 59
  3. Very specific:

    Create and link freely; update_memory and mark_memory_obsolete rewrite history, so those two always get user confirmation before executing.

    line 69
  4. Distinctive:

    Do not automatically retry, invent new facts to satisfy a check, or claim a rejected write succeeded.

    line 106
  5. Distinctive:

    If a request is cancelled or its response is lost, check stored state before retrying: persistence may already have completed.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Remembering knowledge in Forgetful

Capture is a sequence, not a single call: route the content to the right store, ground it in a project, check what already exists, then create atomically and link. Removal and rewriting happen by supersession only — a memory does not become less true because it hasn't been queried lately.

Invoking operations

Operations are named by registry name (query_memory, create_memory, ...). Invoke via whichever surface this agent has:

  • MCP: execute_forgetful_tool(tool_name="create_memory", arguments={...})
  • CLI: forgetful call create_memory --args '{"title": "..."}' --json

Get any operation's schema at runtime: how_to_use_forgetful_tool (MCP) or forgetful tools info <operation> (CLI) — schemas are deliberately not repeated here.

Step 1 — Route the type

The content is...Store asWhere
A single fact, decision, or preferenceMemorythis skill, step 4
Detailed analysis or a guide (>300 words)Document + entry memoriesthis skill, step 4
Reusable codeCode artifactthis skill, step 4
A person, org, device, product, componentEntityforgetful-entities
Step-by-step procedural knowledgeSkillforgetful-procedures
Binary content (image, PDF, asset)Fileforgetful-files
A goal decomposing into steps / a work itemPlan / Taskfeature-flagged; check discovery

Done when: exactly one type is chosen, and routed-away types are handled by their skill.

Step 2 — Resolve the project

Every write needs a deliberate project decision. Derive the candidate from the repo: git remote get-url origin → owner/repo → list_projects with repo_name. When no project matches, create one or ask the user; when several could apply, ask.

Done when: a real project_id is confirmed — discovered or user-chosen, never assumed.

Step 3 — Query before create

Search for overlapping knowledge using the candidate's own essence as the query (query_memory with query and query_context). Classify every relevant hit:

Existing memory is...Action
Still accurate and covers the pointLink to it if related; skip creating a duplicate
Right but missing the new detailUpdate it — confirm with the user first
Contradicted by the new knowledgeMark obsolete (confirm first) + create replacement
Overlapping but a distinct conceptCreate new, then link_memories both

Create and link freely; update_memory and mark_memory_obsolete rewrite history, so those two always get user confirmation before executing.

Done when: every hit is classified and the create/update/skip decision is explicit.

Step 4 — Create atomically

The atomicity test, before writing: Can the title say it in ~10 words? Is it self-contained without reading other memories? Is it ONE decision, fact, or pattern? A sprawling "Project X overview" fails the test — split it.

  • Ideal content is 200–400 words. Limits: title ≤200 chars, content ≤2000, context ≤500, keywords ≤10, tags ≤10.
  • Set importance from the rubric below. About 70% of memories belong at 7–8; reserve 9–10.
BandUse for
9–10Foundational: personal facts, architectural principles in constant use
8–9Critical solutions, major decisions
7–8Useful patterns, strong preferences, tool choices, standard implementations
6–7Milestones, minor context
5Noise floor: bulk/automated captures meant to stay out of normal recall
  • Stamp provenance when derived from source material: source_repo, source_files, source_url.

Long-form variant: content over ~300 words becomes create_document, then 3–7 atomic memories as entry points, each linked to the document via document_ids. Reusable code becomes create_code_artifact, with a memory pointing at it when the decision behind the code matters too.

Review plugin_warnings on create/update/obsolete/restore success. The write already succeeded; report the warning and consider the stated correction without repeating it. Near-duplicate warnings are advisory after creation. MEMORY_PLUGIN_AFTER_SAVE_UNAVAILABLE means the write succeeded but its after-save check failed. WRITE_PLUGIN_REJECTED means the write did not happen: correct the stated issue within the user's authorized scope before trying again. WRITE_PLUGIN_UNAVAILABLE means the configured check could not complete; report it. Do not automatically retry, invent new facts to satisfy a check, or claim a rejected write succeeded. If a request is cancelled or its response is lost, check stored state before retrying: persistence may already have completed.

Done when: the object exists, atomic, scored, provenance-stamped where applicable, and any Memory Plugin warning has been reviewed.

Step 5 — Link

Auto-linking connects each new memory to its nearest neighbours (similarity ≥ 0.7 by default). Review what it picked up, then add link_memories manually only for the four kinds embeddings miss: cross-domain connections, prerequisite chains, contrast (this-not-that), and evolution (old approach → new approach).

Done when: auto-links reviewed and any of the four manual kinds added.

Step 6 — Announce

This skill is the single source of truth for the announcement convention. After saving with importance ≥ 7:

💾 Saved to memory: "<title>"
   Tags: <tags>
   Related: <linked memory titles>

Done when: the user can see what was saved and how it connected.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.