### Manual Setup: Install Agent Skill

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Install the agent skill to enable automatic invocation of Linksee Memory features.

```bash
npx -y linksee-memory-install-skill
```

--------------------------------

### Manual Setup: Add MCP Server

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Manually install and register the Linksee Memory MCP server using this command.

```bash
claude mcp add -s user linksee -- npx -y linksee-memory
```

--------------------------------

### Setup Linksee Memory

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Run this command to set up linksee-memory. It is a single command for a complete setup.

```bash
npx linksee-memory-setup
```

--------------------------------

### Record Demo with VHS

Source: https://github.com/michielinksee/linksee-memory/blob/main/demo/DEMO.md

Generate a GIF of the demo by installing vhs and running the 'where-demo.tape' script.

```bash
cd demo && vhs where-demo.tape
```

--------------------------------

### Example Recall for 'KanseiLink new tool'

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

An example of a recall query when the user wants to add a new tool to KanseiLink.

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

--------------------------------

### Manual Setup: Configure Auto-Capture

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Add this JSON configuration to your ~/.claude/settings.json to enable auto-capture of sessions.

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}
```

--------------------------------

### Verify LinkSee Memory Skill Installation

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Check if the LinkSee Memory skill is installed in the Claude environment. If it's missing, run the installation command.

```bash
ls ~/.claude/skills/linksee-memory/SKILL.md
```

--------------------------------

### Example Caveat Content

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

An example of the content structure for a 'caveat' layer memory, detailing a specific failure scenario.

```json
{
  "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"}]
}
```

--------------------------------

### LinkSee Memory Server CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Starts the LinkSee Memory MCP server using standard input/output.

```bash
npx linksee-memory
```

--------------------------------

### LinkSee Memory Install Skill CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Installs the Claude Code Skill, which teaches the agent when to use recall, remember, and read_smart commands.

```bash
npx linksee-memory-install-skill
```

--------------------------------

### Example: Proactive Caveat for npm Publish

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Demonstrates the proactive caveat surfacing pattern when about to run 'npm publish'. It recalls potential issues related to the action and presents a specific caveat to the user.

```pseudocode
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?"
```

--------------------------------

### Example Evaluation Against North Star

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Illustrates how to evaluate candidate proposals against the defined North Star. This helps in deciding whether to surface or dismiss proposals based on project alignment.

```text
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)
```

--------------------------------

### Effective Recall Query Examples

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Examples of effective recall query styles for different scenarios, including entity+topic, error recall, decision recall, and cross-entity recall.

```javascript
recall({ query: "KanseiLink OAuth" })
```

```javascript
recall({ query: "401 freee token expired" })
```

```javascript
recall({ query: "Linksee Memory plugin vs MCP" })
```

```javascript
recall_file({ path_substring: "server.ts" })
```

```javascript
recall({ query: "KanseiLink" })
```

```javascript
recall({ query: "Linksee Memory" })
```

--------------------------------

### Drift Status Check

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

This example shows the output of checking the drift status, indicating the number of held and aligned anchors.

```text
You:    What's drifting right now?
Agent:  [calls drift_status]

        28 anchors: ⚪ 1 held · 🔵 27 aligned

        Needs attention:
        ⚪ HELD — "Focus on 4 areas: Recipe layer, agent-native API,
           Japanese market, Agent Insights"
           ↻ Reopens 2026-07-04

        Everything else is aligned — no unaccounted divergence.
```

--------------------------------

### Precise Recall Query Example

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

An example of a precise recall query using keywords and a layer filter to achieve specific results.

```javascript
recall({ query: "auth bug fix caveat", layer: "caveat" })
```

--------------------------------

### Configure Re-injection Guard Hooks in .claude/settings.json

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

This JSON configuration enables the linksee-memory-guard for 'SessionStart' and 'PreToolUse' events within a project. It specifies the command to run and a timeout for the guard. Ensure the guard is installed via npm or yarn.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 15 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 8 }
        ]
      }
    ]
  }
}
```

--------------------------------

### LinkSee Memory Structure Example

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Illustrates the 3-axis structured format for memories, including title, altitude, type, state, what, why, affects, and next_action. This format is used across the six memory layers.

```json
{
  "title": "freee OAuth token expires in 24h",
  "altitude": "implementation",
  "type": "outcome",
  "state": "done",
  "what": "freee OAuth token expires in 24 hours. Must refresh proactively.",
  "why": "freee uses short-lived tokens unlike most SaaS (usually 30-90 day expiry)",
  "affects": ["src/integrations/freee/auth.ts"],
  "next_action": null
}
```

--------------------------------

### Triage Whole Project Status

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Run 'linksee-memory-map status' to get a project-wide health percentage, identify fixable issues, and view deferred items.

```bash
$ linksee-memory-map status
```

--------------------------------

### Dry Run Verification Output

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v6.md

Example output from a dry run of the drift detection tool on a clean corpus, showing no detected edits or emitted edges.

```text
anchorsScanned 10, editsScanned ~6.28k, contradicts 0, absent 0, edgesEmitted
0, persisted false, byAnchorHits []
```

--------------------------------

### Persist Flag Verification Output

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v6.md

Example output when using the `--persist` flag on a clean corpus, confirming that it runs without error and results in no writes to the drift_edges table.

```text
same counts, edgesEmitted 0, persisted true
```

--------------------------------

### Run Demo Commands

Source: https://github.com/michielinksee/linksee-memory/blob/main/demo/DEMO.md

Navigate to the demo directory and execute the primary linksee-memory-map commands to analyze a file's context and project status.

```bash
cd demo
linksee-memory-map where README.md   # where am I, and what does this file touch?
linksee-memory-map explain readme    # why this state? — reality says DRIFT, with evidence
linksee-memory-map status            # whole-project triage
```

--------------------------------

### Explain File State on Project Map

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Use the 'explain' command to understand the declared state and reality of a file on the project map, including evidence of agreement or divergence.

```bash
$ linksee-memory-map explain readme

STATUS
  declared: healthy (active)
  reality:  implemented / matches
  verdict:  declared and reality agree (verified)

EVIDENCE
  ✓ README's Tools section lists where_am_i
      README.md:424 — found "where_am_i" in section "Tools"
```

--------------------------------

### Ineffective Recall Query Examples (Anti-patterns)

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Examples of recall queries to avoid due to vagueness or poor FTS5 scoring, such as using natural language sentences or overly broad terms.

```javascript
recall({ query: "what happened" })
```

```javascript
recall({ query: "the user said to fix the bug in the auth flow" })
```

--------------------------------

### Diagnose Project Drift

Source: https://github.com/michielinksee/linksee-memory/blob/main/demo/DEMO.md

Employ the 'explain' command to understand why a project's state is drifting by comparing declared status with reality, supported by evidence.

```bash
$ linksee-memory-map explain readme

STATUS
  declared: healthy (active)
  reality:  drifted
  verdict:  declared vs reality disagree (drift)

WHY
  The README documents an --export flag, but src/cli.js does not implement it.

EVIDENCE
  ✓ README documents the --export flag      demo/README.md:11 — found "--export"
  ✗ src/cli.js implements --export          src — "--export" not found

FIX
  1. implement --export in src/cli.js
  2. or drop the --export claim from the README
```

--------------------------------

### Record Demo with Asciinema

Source: https://github.com/michielinksee/linksee-memory/blob/main/demo/DEMO.md

Capture a terminal session of the demo commands using asciinema for recording and uploading.

```bash
asciinema rec where-demo.cast
ascinema upload where-demo.cast
```

--------------------------------

### LinkSee Memory Stats CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Provides a summary of the local database, including entity counts, layer breakdowns, and top entities/files. Use the --json flag for machine-readable output.

```bash
npx linksee-memory-stats
```

--------------------------------

### TypeScript Build and Execution Check

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v6.md

Commands to verify the TypeScript project's build status and execute the newly added drift detection binary.

```bash
tsc --noEmit
npm run build
node dist/bin/detect-drift.js
tsx src/bin/detect-drift.ts
```

--------------------------------

### Recall Project Context

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

When returning to a project, use this recall query to retrieve relevant past caveats, learnings, or goals. This helps in resuming work with grounded context.

```javascript
recall({ query: "XYZ", max_tokens: 2500 })
```

--------------------------------

### CLI Usage for Drift Detection

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v6.md

Demonstrates the various command-line options for the `linksee-memory-detect` tool, including dry runs, persisting changes, and overriding staleness and threshold parameters. Safe by default with dry-run.

```bash
linksee-memory-detect                  # DRY RUN — preview drift, writes NOTHING (default)
linksee-memory-detect --persist         # write contradicts/absent edges into drift_edges
linksee-memory-detect --stale-days 30   # override absence staleness gate (default 14)
linksee-memory-detect --threshold 0.5   # override emit threshold (default 0.5)
```

--------------------------------

### Stale Days Flag Verification Output

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v6.md

Example output when overriding the absence staleness gate with `--stale-days 0`, showing no false absence fires even with the gate fully open.

```text
still absent 0
```

--------------------------------

### Unified Recall Tool for Search, File History, and Overview

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

The 'recall' tool consolidates search, file history, and entity overview functionalities. Mode is inferred from parameters.

```javascript
recall({ path: "server.ts" })
recall({})

```

--------------------------------

### Agent Memory Recall (With Linksee)

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Shows how linksee-memory allows an agent to recall specific 'why' details from previous sessions, preventing repeated mistakes.

```text
You:    We deployed last week but it crashed. How did we fix it?
Claude: Let me check my caveats...

        🧠 [caveat] NextAuth sessions invalidate when JWT_SECRET
           rotates — redeploy all affected projects in parallel.
           (from session 2026-04-13, importance: 0.9)

        Is this the deploy you're asking about? We hit it when
        we rotated secrets mid-flow.

You:    Yes, exactly. Let's not repeat that.
```

--------------------------------

### Re-index Existing History with LinkSee Memory

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Run the importer to re-index existing history with correct project attribution, fixing entity detection bugs from older versions.

```bash
npx linksee-memory-import --all
```

--------------------------------

### Locate File on Project Map

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Use the 'where' command to find which node a file belongs to on the project map and see its dependencies.

```bash
$ linksee-memory-map where README.md
"README.md" belongs to this Map node:

  readme  [understand]  convergence
    changes ripple to:
      must fix together (hard):  lp, docs-site
      should align (soft):       onboarding, client-configs
      fyi (may ripple):          telemetry-contract
```

--------------------------------

### LinkSee Memory Guard CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Implements the re-injection guard hook, acting as a PreToolUse gate for Edit, Write, and Bash commands, and a SessionStart boot digest. It is wired per-project and fails open.

```bash
npx linksee-memory-guard
```

--------------------------------

### List Entities for Task Context

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Use list_entities at the beginning of a conversation to understand known projects. This helps identify high-momentum entities for subsequent recall.

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

--------------------------------

### LinkSee Memory Import CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Facilitates batch importing of Claude Code session JSONL history.

```bash
npx linksee-memory-import
```

--------------------------------

### Check MCP Registration for LinkSee

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Verify that the MCP is registered under the 'linksee' name, as the skill expects tool names prefixed with 'mcp__linksee__'.

```bash
claude mcp list | grep linksee
```

--------------------------------

### LinkSee Memory Sync CLI

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Serves as the entry point for the Claude Code Stop-hook.

```bash
npx linksee-memory-sync
```

--------------------------------

### Integration with KanseiLink Skill

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Illustrates how linksee-memory and KanseiLink skills collaborate. linksee-memory recalls past caveats and learnings, while KanseiLink verifies external services and provides tips, enriching the user's context before an action.

```pseudocode
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
```

--------------------------------

### Determine File Context and Impact

Source: https://github.com/michielinksee/linksee-memory/blob/main/demo/DEMO.md

Use the 'where' command to identify the Map node a file belongs to and list the other project components it affects.

```bash
$ linksee-memory-map where README.md
"README.md" belongs to this Map node:

  readme  [understand]  divergence
    changes ripple to:
      must fix together (hard):  cli-engine, docs-site
      should align (soft):       npm, onboarding
```

--------------------------------

### Unified Remember Tool for Create, Update, Delete

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

The 'remember' tool unifies create, update, and delete operations. The mode is inferred from the provided parameters.

```javascript
remember({ forget: true, memory_id: <id> })
remember({ memory_id: <id>, content: "..." })

```

--------------------------------

### LinkSee Memory Stats CLI (JSON Output)

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Generates machine-readable statistics for the local LinkSee Memory database.

```bash
npx linksee-memory-stats --json
```

--------------------------------

### Pre-decision Check for Existing Decisions

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Before recording a new decision, this snippet checks for and surfaces any past decisions on the same topic to prevent flip-flopping and build on prior reasoning. It's used when a user proposes a change that might conflict with a previous decision.

```pseudocode
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)
```

--------------------------------

### Cursor Editor Configuration

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Configure Linksee Memory for the Cursor editor by adding this JSON to your ~/.cursor/mcp.json.

```json
{
  "mcpServers": {
    "linksee": {
      "command": "npx",
      "args": ["-y", "linksee-memory"]
    }
  }
}
```

--------------------------------

### Shelling out to the drift detection binary

Source: https://github.com/michielinksee/linksee-memory/blob/main/documents/drift-detection-design-v7.md

This function shells out to the v6 built binary to refresh drift detection. It is throttled to run at most once every 4 seconds and includes fail-safe error handling to prevent page rendering failures. The binary path can be configured via an environment variable.

```typescript
import { execFile } from "child_process";
import { promisify } from "util";

const execFileAsync = promisify(execFile);

const LINKSEE_MEMORY_BIN =
  process.env.LINKSEE_MEMORY_BIN || "~/linksee-memory/dist/bin/detect-drift.js";

let lastRefresh = 0;

export async function refreshDrift() {
  if (Date.now() - lastRefresh < 4000) {
    return;
  }
  lastRefresh = Date.now();

  try {
    const { stdout, stderr } = await execFileAsync(LINKSEE_MEMORY_BIN, [
      "--persist",
    ]);
    if (stderr) {
      console.error(`[drift] exec error: ${stderr}`);
    }
    // Example log line: [drift] on-load detect ran contradicts=N absent=N edges=N
    console.log(`[drift] on-load detect ran ${stdout}`);
  } catch (e: any) {
    console.error(`[drift] exec error: ${e.message}`);
    // Fail-safe: log error, return, page still renders last-known edges.
  }
}
```

--------------------------------

### Enable LinkSee Telemetry

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

Set the LINKSEE_TELEMETRY environment variable to opt-in to basic anonymous telemetry. To opt-out, set it to 'off' or unset the variable.

```bash
export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)
```

--------------------------------

### Local Development Guard Hook Configuration

Source: https://github.com/michielinksee/linksee-memory/blob/main/README.md

This JSON configuration is used when developing linksee-memory itself. It points the guard hook to a local build of the guard script, allowing for testing against uncommitted changes.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          { "type": "command", "command": "node ${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js", "timeout": 15 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [
          { "type": "command", "command": "node ${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js", "timeout": 8 }
        ]
      }
    ]
  }
}
```

--------------------------------

### Smart File Reading

Source: https://github.com/michielinksee/linksee-memory/blob/main/src/skill/SKILL.md

Use read_smart instead of the standard Read tool for files, especially large ones. It significantly reduces token usage on subsequent reads of unchanged files or parts of files.

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