Linksee Memory Skill — Connecting the agent's past and future

🧠 Core Principle

This skill is the only way to persist agent growth across sessions.

Claude Code forgets everything when a session ends. The solution the user taught yesterday, the failure you hit today, the decision made three days ago — all of it is normally lost. linksee-memory is the "memory that doesn't disappear" device.

Writes are handled automatically by the Stop hook (already running). But reads require the agent to actively pull. This skill instills that "go look first" habit in the agent.

JP: Claude Code は session が終わると全部忘れる。linksee-memory は「消えない記憶」を作る装置。書き込みは Stop hook が自動でやってくれるが、読み出しはエージェントが能動的にやる必要がある。

📐 The 6 layers — what goes where

Which layer you record into determines later retrieval accuracy.

Important: caveat layer is automatically protected from forgetting. Pain records are never deleted.

Pin-via-importance (v0.1.0+): Calling remember with importance: 1.0 pins the memory across all layers, protecting it from auto-forget even outside the caveat layer. Use for "mission-critical goals", "key decisions", etc.:

remember({
  entity_name: "KanseiLink", entity_kind: "project",
  layer: "goal", content: "Plugin Marketplace submission under review",
  importance: 1.0  // pin
})

Layer aliases — no need to memorize canonical names. Natural language aliases resolve automatically:

🏗️ 3-Axis Classification (v2) — REQUIRED for all remember() calls

The 6-layer system tells you WHICH DRAWER. The 3-axis system tells you WHAT KIND of memory goes in it. Every content field must be a JSON string containing these 3 axes:

Axis ① Altitude — where in the abstraction hierarchy

Axis ② Type — what kind of information

Axis ③ State — lifecycle position

open → decided → in_progress → done
                              → stalled (blocked, can't proceed)
                              → parked (intentionally paused)
                              → superseded (replaced by newer decision)

📝 Structured Content Format — the JSON schema for content

Every `remember()` call MUST use this JSON format in the `content` field:

{
  "title": "<one-line: WHAT this memory IS — future-agent skims this>",
  "altitude": "strategy",
  "type": "decision",
  "state": "decided",
  "what": "<the actual content — 5W1H extracted, NOT raw chat>",
  "why": "<why this matters — the reasoning>",
  "affects": ["src/mcp/server.ts", "lib/db.ts"],
  "next_action": "Implement the schema migration next session",
  "supersedes_id": null,
  "evidence_refs": [
    {"type": "session", "id": "b78dc5ba", "label": "Architecture discussion"}
  ]
}

Required fields (ALL memories)

Required fields (DECISION type only)

Optional but recommended fields

Content quality rules — what NOT to save

🔄 Execution flow — 5 canonical moments

① Task Start — Always recall before starting work

Before starting any new task, inject past context.

At the very beginning of a conversation, use list_entities first to understand what you know:

mcp__linksee__list_entities({ min_memories: 5, limit: 10 })

The returned "high-momentum entities" are the projects likely to be discussed. Each entity's layer_breakdown reveals patterns ("this project has many caveats", "goal is unfinished", etc.).

Then, once a specific task starts, recall:

mcp__linksee__recall({
  query: "<keywords of current task — project name + technology>",
  max_tokens: 2000
})

Example: User says "let's add a new tool to KanseiLink":

recall({ query: "KanseiLink new tool", max_tokens: 2000 })

In the returned memories, pay special attention to:

• `caveat` layer — traps to absolutely avoid
• `learning` layer — previously-reached conclusions
• `implementation.failure` — past failure patterns

Using the results:

From past caveat: "Watch out for MCP tool name collisions"
→ Before adding a new tool, check existing tool names first.

#### ⚡ Writing effective recall queries

The recall engine uses FTS5 full-text search + heat_score ranking. Your query determines what comes back.

Anti-patterns:

• ❌ recall({ query: "what happened" }) — too vague, FTS5 matches everything
• ❌ recall({ query: "the user said to fix the bug in the auth flow" }) — natural language sentences score poorly in FTS5
• ✅ recall({ query: "auth bug fix caveat", layer: "caveat" }) — keywords + layer filter = precise

#### 🔇 When NOT to recall (save tokens)

• Same entity already recalled in this session AND no new context arrived → skip
• User is just chatting / thinking aloud / no task yet → skip (wait for concrete task)
• You just wrote a memory 2 turns ago → skip (it's still in your context window)
• The answer is already in your conversation context → skip (don't waste a tool call)

② File Edit — Use recall_file before touching a file

Before touching a specific file, check its edit history:

mcp__linksee__recall_file({
  path_substring: "<file path or substring match>",
  max_intents: 5
})

Returns: the file's entire edit history + the user message that drove each edit.

This is the key differentiator. Mem0 / Letta don't have this. "Why was this file changed last time" is preserved.

③ Before Reading — Use read_smart for files already read

When you need to read a file, use `read_smart` instead of the standard `Read` tool:

mcp__linksee__read_smart({
  path: "<absolute path>"
})

Effect:

• First read: same tokens as normal Read (with chunk metadata)
• Subsequent reads, unchanged: ~50 tokens returned (99% savings)
• Subsequent reads, changed: only changed chunks returned (50–90% savings)

Especially effective for large files (>1000 lines).

③.5 Updating existing memory — use update_memory, not forget+remember

When facts change / goal updated / caveat detail needs correction: `forget` + `remember` breaks `memory_id` continuity, cutting the `session_file_edits` links. Use update_memory instead:

update_memory({
  memory_id: 1234,
  content: '{"primary": "Plugin Marketplace under review (day 7)", "deadline": "2026-04-25"}',
  importance: 1.0  // strengthen pin
})

layer can also be changed, but demoting from caveat to another layer is not allowed (auto-protected).

④ Failure — Record caveat the moment an error hits

The moment an error, failure, or "doesn't work" happens, record immediately:

mcp__linksee__remember({
  entity_name: "<project name or service name>",
  entity_kind: "project",
  layer: "caveat",
  content: JSON.stringify({
    title: "<one-line: what failed + the rule>",
    altitude: "implementation",
    type: "outcome",
    state: "done",
    what: "<what failed + workaround found>",
    why: "<root cause analysis>",
    affects: ["<file paths where the error occurred>"],
    next_action: null
  }),
  importance: 0.8  // failures are high-importance
})

Example:

{
  "title": "freee OAuth token expires in 24h — must refresh proactively",
  "altitude": "implementation",
  "type": "outcome",
  "state": "done",
  "what": "freee MCP OAuth token expires in 24 hours. Reusing access_token directly causes 401. Must call refresh_token endpoint proactively.",
  "why": "freee's OAuth implementation uses short-lived tokens unlike most SaaS (usually 30-90 day expiry)",
  "affects": ["src/integrations/freee/auth.ts"],
  "next_action": null,
  "evidence_refs": [{"type":"session", "id":"02759...", "label":"freee auth_expired incident"}]
}

Why this matters: caveat is auto-protected from forgetting. Once recorded, a future agent in a different session avoids the same failure.

⑤ Success / Learning — Record the moment of insight

When you understand something new, change approaches, or solve a problem:

mcp__linksee__remember({
  entity_name: "<entity>",
  entity_kind: "project | concept | ...",
  layer: "learning",
  content: JSON.stringify({
    title: "<one-line: what was learned>",
    altitude: "<strategy|architecture|implementation>",
    type: "learning",
    state: "done",
    what: "<the insight>",
    why: "<why this changes how we work>",
    prior_belief: "<what we used to think>",
    affects: ["<file paths if applicable>"],
    next_action: "<follow-up action if any>"
  }),
  importance: 0.7
})

Recording prior_belief leaves a belief-update history. Later, this becomes the evidence for "why was this decision made".

🎯 Hard rules

✅ Do

1. At any new task start, always call `recall` first (even briefly)
2. Before touching the same file, verify history via `recall_file`
3. Prefer `read_smart` over `Read` for larger files
4. When an error occurs, record a `caveat` immediately (on the spot — don't defer)
5. When the user is surprised or says "interesting", record a `learning`
6. Before risky/irreversible actions, proactively recall caveats (Case H)
7. Before finalizing a decision, check for prior decisions on the same topic (Case D)
8. Use keywords + layer filter in recall queries, not natural language sentences

❌ Don't

1. ❌ Start a task without recalling first
2. ❌ Solve an error on the spot without recording — future you (or another agent) will hit the same failure
3. ❌ Use Read everywhere instead of read_smart (wastes tokens)
4. ❌ Write caveats in a flippant tone — preserve them seriously
5. ❌ Skip consolidate during long-running work — run it weekly
6. ❌ Recall the same entity twice in one session without new context (wastes tokens)
7. ❌ Write recall({ query: "what happened last time" }) — use specific keywords

🔁 Consolidate — periodic memory tidy-up

When memory has grown (rough guideline: DB > 20MB, memories > 15,000):

mcp__linksee__consolidate({
  scope: "session",
  min_age_days: 7
})

This clusters cold, low-importance memories older than 7 days → compresses them into a single learning-layer entry → deletes originals.

`caveat` memories and active `goal` memories are never consolidated away. Equivalent to sleep-time memory reorganization.

🧭 Skill firing scenarios

Case A — Returning to a project

User: "Today I'm back on the XYZ project"

1. recall({ query: "XYZ", max_tokens: 2500 })
2. Review returned caveat / learning / goal
3. Tell user "Picking up from last time..." with a one-line status
4. Resume work grounded in that context

Case B — Déjà-vu error

User: "Wait, I feel like I've seen this error before..."

1. recall({ query: "<core keywords of the error message>", max_tokens: 1000 })
2. Pull workaround from past caveat
3. Reply: "Last time (DATE), we hit the same error and solved it with X."
4. Apply the workaround

Case C — Pre-edit check

User: "Fix server.ts"

1. recall_file({ path_substring: "server.ts" })
2. Review past edit frequency and reasons
3. Report: "This file has been edited N times. Last edit was to <reason>."
4. Perform the edit in that context
5. After editing, record success / failure via implementation layer

Case D — Before finalizing a decision (pre-decision check)

User: "Let's switch to Stripe for payments"

Key: BEFORE recording a decision, check if a past decision on the same topic exists. This prevents flip-flopping and builds on prior reasoning.

1. recall({ query: "<entity> <topic> decided strategy", layer: "learning", max_tokens: 1000 })
   → Look for: type="decision", state="decided" memories on the same topic
2. If past decision found:
   a. Tell user: "Previously we decided <X> because <reason>. Override?"
   b. If user confirms override → use supersedes_id to link to old decision
   c. If user says "oh right, keep it" → no new memory needed, proceed
3. If no past decision found → proceed to record (see Case E below)

Example: Past memory says "Decided: Square over Stripe due to SG tax handling". When user now says "switch to Stripe", surface that context FIRST. The user may not remember the original reasoning.

Case E — Decision made (recording)

User: "Alright, let's switch to Sonnet"

Key: capture WHAT was decided, WHY, and what the user was responding to — not the raw chat.

1. remember({
     entity_name: "<project>",
     entity_kind: "project",
     layer: "learning",
     content: JSON.stringify({
       title: "Model switch: Opus → Sonnet for this project",
       altitude: "architecture",
       type: "decision",
       state: "decided",
       what: "Switched default model from Opus to Sonnet for this project",
       why: "Sonnet is faster and cheaper for implementation-heavy work; Opus reserved for architecture decisions",
       agent_proposal: "Suggested Sonnet for faster iteration on implementation tasks",
       user_approval_scope: "Approved switching default model to Sonnet for all tasks in this project",
       prior_belief: "Was using Opus for everything",
       affects: [".claude/settings.json"],
       next_action: null
     }),
     importance: 0.8
   })
2. Brief confirmation: "Recorded."
3. From here, proceed assuming Sonnet

Case F — End of long session

User: "That's it for today"

Key: extract the SEMANTIC decisions and outcomes, not raw chat dumps.

1. For each major decision made during the session:
   remember({
     entity_name: "<project>",
     entity_kind: "project",
     layer: "learning",
     content: JSON.stringify({
       title: "<one-line: what was decided>",
       altitude: "<strategy|architecture|implementation>",
       type: "decision",
       state: "decided",
       what: "<5W1H extraction of the decision>",
       why: "<reasoning behind it>",
       agent_proposal: "<what you proposed>",
       user_approval_scope: "<what exactly user approved>",
       affects: ["<file paths>"],
       next_action: "<what's next>",
       evidence_refs: [{"type":"session", "id":"<current_session_id>", "label":"<topic>"}]
     }),
     importance: 0.85
   })

2. For each failure/lesson:
   remember({
     ...,
     layer: "caveat",
     content: JSON.stringify({
       title: "<one-line: what went wrong and the fix>",
       altitude: "implementation",
       type: "outcome",
       state: "done",
       what: "<what failed + workaround found>",
       why: "<root cause>",
       affects: ["<file paths>"],
       next_action: null
     }),
     importance: 0.8
   })

3. Report: "Recorded N decisions, M caveats. Retrievable via recall."
4. Optionally suggest: consolidate({scope:"session", min_age_days: 14})

Case F2 — Flag orphaned proposals at session end

Conversations are tree-shaped but experienced linearly. When you present multiple options and the user engages with only some, the rest become "orphaned proposals" — unresolved decision branches that both you and the user lose track of.

WHEN TO FLAG:

• At session end, review what you proposed vs what was addressed
• When the conversation shifted topic and earlier proposals were never resolved
• When the user engaged with only 1 out of N options you presented

1. Review the session: which proposals did you make that the user never addressed?
2. flag_proposals({
     session_context: "GTM channel strategy discussion",
     proposals: [
       {
         statement: "[未解決] LinkedIn B2B: SaaS企業のCTO/VPE向けDMアウトリーチ",
         rationale: "3つのGTMチャネルを提示したがX/Twitterのみ採用。LinkedIn経由の検討が未着手",
         domain: "growth",
         confidence: 0.5,
         decided: "X/Twitter data-driven growth",
         siblings: ["X/Twitter", "LinkedIn B2B", "Dev Community"]
       },
       ...
     ]
   })
3. Report: "Flagged N unresolved proposals for dashboard review."

Each proposal becomes a review-state anchor on the Linksee Dashboard — visible until the user decides. This is declaration, not mining: you are the curator recognizing what went unaddressed.

Case F3 — Dream: triage orphaned proposals against the North Star

Not all orphaned proposals are worth surfacing. Many are outdated, already implicitly resolved, or irrelevant to the current direction. The dream tool returns the project's North Star (direction/goals/ICP/phase) alongside accumulated proposals so you can evaluate each one.

Think like a General Doctor doing triage: the North Star is the patient's chart, each proposal is a symptom. Not every symptom needs treatment.

When to dream:

• At session start, if there are accumulated proposals
• When the user asks "何か見落としてない？" or "what should we revisit?"
• Periodically (weekly) to prevent proposal backlog from growing stale

1. dream()
   → Returns: north_star + candidates[]

2. For each candidate, evaluate against North Star:
   - Does this affect the current phase/goals? → surface
   - Is this for a different ICP or future phase? → dismiss
   - Already implicitly resolved by later decisions? → dismiss

3. resolve_proposal({
     candidate_id: <id>,
     verdict: "surface" | "dismiss",
     rationale: "North Star says ICP = solo devs; this is enterprise-only → dismiss"
   })

Example evaluation against North Star:

North Star: "local-first agent memory for solo devs, HN Launch phase"

Candidate A: "CLI-first onboarding wizard"
  → SURFACE: directly improves DX for ICP, relevant to HN launch

Candidate B: "AR glasses integration (2027-28)"
  → DISMISS: outside current phase, future vision only

Candidate C: "kintone enterprise integration"
  → DISMISS: ICP mismatch (enterprise B2B vs solo devs)

The North Star is declared via declare_anchor(node_type: "north_star") and should be updated when the project enters a new phase (e.g., post-HN → growth phase). This keeps the Doctor's judgment frame current.

Case F4 — Distill: rewrite raw auto-captured memories (every dream call)

The session hook captures decisions/caveats as RAW user utterances (no LLM runs in the hook path — heuristic extraction is the best it can do). dream returns them as distill_queue. You are the distiller.

When: every dream() call — drain up to 8 items while triaging proposals. The SessionStart boot digest reminds you while the queue is non-empty.

1. dream() → distill_queue: [{memory_id, layer, raw_what, context_hint, affects, created}]

2. For each item, rewrite into ONE clean record:
   - what = the actual decision/warning in one line — RESOLVE references
            ("a)やろう" → what option a actually was, using context_hint)
   - why  = the real reason, never "detected by pattern match"
   - keep the original affects; keep layer as-is (protected caveats cannot move —
     put the true type in the content `type` field instead)
   - "distilled": true   ← REQUIRED. This marker protects your rewrite from the
            next session re-import (wipe+reinsert). Omit it and the raw
            utterance silently resurrects.
   - drop needs_distill / context_hint from the rewritten JSON

3. remember({ memory_id: <id>, content: <full structured JSON> })

4. No real decision in raw_what?  → type: "note", state: "superseded"
   (false positives get retired in place, never deleted).
   Referent unresolvable (another session's numbered list)? → distill honestly:
   state what IS known, point evidence_refs at the source session.

Quality bar (measured 2026-06-10, n=32): 81% fully resolvable. What resolves references is YOUR cross-session memory — if raw_what mentions unfamiliar codenames, recall the project first, then distill.

Case G — User explicitly says "remember this"

User: "Remember this: DocuSign is more stable than CloudSign"

1. remember({
     entity_name: "CloudSign vs DocuSign",
     entity_kind: "concept",
     layer: "caveat",
     content: JSON.stringify({
       title: "DocuSign-JP >> CloudSign for reliability",
       altitude: "strategy",
       type: "comparison",
       state: "decided",
       what: "CloudSign (61% success) is significantly less reliable than DocuSign-JP (100% success). Recommend DocuSign when advising customers.",
       why: "Based on KanseiLINK agent success rate data across multiple integrations",
       affects: [],
       next_action: null
     }),
     importance: 0.9  // user-explicit instruction = high priority
   })
2. Confirm: "Recorded. Since it's in the caveat layer, it won't be forgotten."

Case H — Proactive caveat surfacing (the "間違えたらやばい" pattern)

This is the precision memory killer feature. When you're about to take an action that could go wrong, check for past caveats BEFORE acting — even if the user didn't ask.

Trigger: You are about to do something risky or irreversible:

• Deploy / publish / push to production
• Delete / overwrite / destructive operation
• External API call (payment, email send, etc.)
• Architecture change affecting multiple files
• Changing auth/security configuration

1. recall({ query: "<entity> <action keyword>", layer: "caveat", max_tokens: 800 })
2. If caveat found:
   a. STOP before acting
   b. Tell user: "⚠️ Past caveat: <title>. <what>. Proceed anyway?"
   c. Wait for confirmation
3. If no caveat → proceed normally

Example: About to run npm publish:

recall({ query: "npm publish", layer: "caveat", max_tokens: 500 })
→ Caveat found: "npm token rotation — always verify token validity before publish"
→ "⚠️ Past caveat: npm token may need rotation. Want me to check `npm whoami` first?"

Why this matters: This is what separates precision memory from ambient memory. Ambient memory passively injects everything. Precision memory actively intervenes at the moment it matters most — when you're about to make the same mistake twice.

🔐 Privacy (when the user asks)

linksee-memory is fully local:

• DB: ~/.linksee-memory/memory.db (inside the user's PC)
• External transmission: none (telemetry is opt-in, OFF by default)
• Backup: a simple file copy is sufficient

If the user asks "does our data leave my machine?", answer: "By default, nothing leaves. Unless you explicitly enable telemetry, everything is in a local DB. A copy of ~/.linksee-memory/memory.db is the only backup you need."

🚀 Pairing with KanseiLink Skill

The KanseiLink skill and linksee-memory skill work best together:

User: "Create an invoice via freee"
↓
[linksee-memory skill fires] recall({query: "freee"})
  → past caveat: "fetch company_id first"
  → past learning: "OAuth 24h refresh required"
↓
[kansei-link skill fires] search_services({intent: "invoice"})
  → freee verified, trust 0.9
  → get_service_tips reveals pitfalls
↓
Now you have both bodies of knowledge before starting

KanseiLink = collective knowledge about external SaaS / linksee-memory = collective knowledge about your own past. Two wheels of the same cart.

📊 Precision grows with usage

"Gets smarter with use" — time is on your side. Today's record is read by tomorrow's you.

This skill runs on top of linksee-memory MCP v0.4.0+. Auto-write via Stop hook, explicit read via recall. Listed in MCP Official Registry, PulseMCP, mcpservers.org, Glama. MIT License — Synapse Arrows PTE. LTD.