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

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:

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.

• 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.

Done when: the object exists, atomic, scored, and provenance-stamped where applicable.

Step 5 — Link

Auto-linking connects each new memory to its nearest neighbours (similarity ≥ 0.7). 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.