agenticluke/knowledge-sync-plus

Knowledge Operations

Manage knowledge across several stores.

Give each fact one main home. Other stores may hold a short note and a link to that home.

Use This Skill When

Use this skill when the user wants to:

• Save facts or notes to a knowledge base.
• Import a file, chat, or data set.
• Sync knowledge between stores.
• Find or merge duplicate notes.
• Search for known facts about a topic.
• Update a shared source of truth.
• Do more than a simple memory lookup.

Main Rules

• Keep code work in the real cloned repo.
• Put live plans and work state in GitHub, Linear, or the repo.
• Put long notes outside the code repo when they do not belong with the code.
• Put long-term, cross-device notes in the knowledge base.
• Search before you create.
• Do not make two main copies of the same fact.
• Do not make outside calls unless the user asks and the needed tool is already set up.
• Never save keys, passwords, tokens, cookies, or private login data.
• Do not commit or push unless the user asks or has already approved that step.
• Do not replace newer facts with older notes.

Storage Layers

1. Live Work Source

Examples:

• GitHub issues, pull requests, talks, and release notes
• Linear issues, projects, and docs
• Files in the real project repo

Use this for:

• Current plans
• Roadmaps
• Release state
• Rollout state
• Build and code work

If a fact changes active work, update this layer first.

2. Claude Code Memory

Path:

~/.claude/projects/*/memory/

Use short Markdown files with YAML frontmatter.

Use this for:

• User choices
• User feedback
• Small project facts
• Short reference notes
• Facts needed in later chats

Do not assume this path exists or can be changed. Check first.

3. MCP Memory

Common tools:

• create_entities
• create_relations
• add_observations
• search_nodes

Use this for:

• Named people, teams, tools, and projects
• Links between those items
• Facts that should be easy to search later

Use exact tool names from the current MCP server. If no memory server is set up, skip this layer and say so.

4. Knowledge Base Repo

Use this for:

• Long-term notes
• Session exports
• Joined research
• Run books
• Long documents

This is the main cross-device store for content that is not project code.

5. Data Store

Examples:

• Supabase
• PostgreSQL

Use this for:

• Large sets of rows
• Large document sets
• Full-text search
• Data that needs SQL

Keep only a short summary and a record ID in memory.

6. Local Notes and Archive

Use this for:

• Notes for people to read
• Old plans
• Local media lists
• Short-term non-code files

Do not use this as a second code repo or as the main home for live plans.

Pick the Main Home

Use this guide:

Knowledge type	Main home	Optional copy
Current plan, release, or code state	GitHub, Linear, or project repo	Short memory note
Business choice	Project memory or knowledge base	MCP memory
User choice or feedback	Claude Code memory	MCP memory
Small reference fact	Claude Code memory	MCP memory
Large document set	Data store or knowledge base	Short memory summary
Chat or session export	Knowledge base repo	Short memory summary
Local, short-term note	Local archive	None

If two choices fit, pick the store that owns the work. Add a link from the other store instead of copying the full text.

Import Steps

1. Read and Sort

Find:

• The source
• The topic
• The date
• The owner
• Whether the facts are current
• Whether the text has secrets
• The best main home

Do not import text you cannot read or trust. Mark unsure facts as unsure.

2. Search for a Match

Before writing:

• Search memory files.
• Search MCP memory when it is set up.
• Search the knowledge base.
• Check GitHub or Linear when they may own the fact.
• Check the target data store when used.

Match by topic, names, dates, IDs, and source links.

3. Handle Copies and Conflicts

If the same fact exists:

• Update the main record.
• Add new source links or dates.
• Keep useful history.
• Remove or mark stale copies only when it is safe.

If two sources disagree:

• Do not guess.
• Keep both claims with their dates and sources.
• Prefer the newer source only when it clearly owns the fact.
• Ask the user when the choice changes work or removes data.

4. Save

Write only to stores that are in scope and ready to use.

• Update the live work source first when active work changes.
• Keep Claude Code memory short.
• Use MCP memory for facts and links.
• Put long text in the knowledge base.
• Put large sets in a data store.
• Add a source, date, and owner when known.

If a store is missing or read-only, save nothing there. Report what could not be done.

5. Update Indexes

Update any topic list, session list, or summary file used to find the new item.

Use lowercase kebab-case file names, such as:

release-plan-2026-05.md

6. Check the Result

Read back each changed record. Make sure links, dates, and names are right.

Sync Work

Sync Chats

For Claude, Codex, or other chat exports:

1. Remove secrets and private login data.
2. Keep the source name and date.
3. Save the full export in the knowledge base.
4. Add a short summary to memory.
5. Update the session index.
6. Commit and push only with user approval.

Sync Workspace State

For key files and settings:

1. Make a folder map.
2. Copy only useful, non-secret facts.
3. Remove keys, tokens, passwords, cookies, and private paths.
4. Note the source and date.
5. Track changes over time.

Do not copy a whole live code folder into an archive.

Sync GitHub or Linear

When a fact changes active work:

1. Find the item that owns the work.
2. Update that item first.
3. Add support docs when needed.
4. Add a local note only if it gives extra value.
5. Link the note back to the main item.

Sync Many Sources

For chats, bookmarks, GitHub events, or other sources:

1. Group items by topic.
2. Remove exact and near copies.
3. Keep source links and dates.
4. Write one clear status note.
5. Save it in the main home.
6. Commit and push only with user approval.

Memory Pattern

Short term:
Use the current task list for work in this chat.

Medium term:
Use short files in ~/.claude/projects/*/memory/.

Long term:
Use GitHub or Linear for live work.
Use the knowledge base for long notes.

Linked facts:
Use MCP memory for items, facts, and links.

Knowledge File Form

---
title: Release plan
type: project
topics:
  - release
  - mobile-app
source: https://example.com/item/123
updated: 2026-05-12
status: current
---

# Release Plan

Short facts go here.

## Links

- Main work item: URL or file path

Use only fields that help. Use an ISO date in YYYY-MM-DD form. Set status to current, stale, archived, or unclear.

Concrete Example

User request:

Save this: The mobile app launch moved from June 1 to June 15. GitHub issue 42 owns the launch plan.

Steps:

1. Search for the launch plan in GitHub, memory, MCP memory, and the knowledge base.
2. Open issue 42 and check that it is the main work item.
3. If allowed, update issue 42 to June 15.
4. Update the old memory note instead of making a new one.
5. Add an MCP fact that the launch date is June 15 and link it to issue 42.
6. Mark any June 1 note as stale. Keep it only if the old date is useful history.
7. Read back the saved date and links.
8. Report each store changed and any store skipped.

Do not update GitHub if the user only asked for a review or search.

Edge Cases

• If the source has no date, say the date is unknown.
• If the owner is not clear, ask before changing a live plan.
• If a file is too large, store it in the knowledge base or data store and keep a short memory note.
• If two items share a name, use IDs, links, owners, and dates to tell them apart.
• If content may be private, save the least amount needed.
• If a secret is found, leave it out. Do not copy or print it.
• If a write partly fails, do not claim the sync is done. List what worked and what failed.
• If a save would delete useful history, archive it or ask first.
• If there is no safe main home, ask the user where it should go.
• If the same fact must appear in two stores, keep the full text in one store. Put a short note and link in the other.

Final Check

Before you finish, confirm:

• No new duplicate was made.
• Each fact has one main home.
• Old facts were updated or marked stale.
• No secret was saved or printed.
• Dates, names, IDs, and links are correct.
• Indexes and summaries are current.
• Cross-links were added when useful.
• All changed records were read back.
• No commit, push, or outside write happened without approval.
• The user is told what changed, what was skipped, and why.