# Cross-Agent Memory
Source: https://docs.linksee.app/concepts/cross-agent
One memory shared across Claude, GPT, Cursor, Codex, Gemini, and any MCP client
## The problem with vendor-locked memory
Claude has built-in memory. So does GPT. But they don't talk to each other.
If you use Claude Code for backend work and Cursor for frontend, your backend decisions are invisible to your frontend agent. Switch to Codex for a deploy script? Start from zero.
## One SQLite, every agent
Linksee Memory stores everything in a **single SQLite file** on your machine. Any MCP-compatible client can read and write to it.
```mermaid theme={null}
graph TB
subgraph Your Machine
DB[(memory.db)]
end
CC[Claude Code] --> DB
CU[Cursor] --> DB
WS[Windsurf] --> DB
CX[Codex CLI] --> DB
GE[Gemini CLI] --> DB
CD[Claude Desktop] --> DB
```
When Claude Code stores a caveat about a Supabase issue, Cursor sees it immediately. When Cursor discovers an API quirk, Codex can recall it.
## No cloud. No account. No sync conflicts.
* The database is a local file — no cloud dependency
* No account registration required
* No API keys to manage
* Multiple agents can read simultaneously (SQLite WAL mode)
* File-level locking prevents concurrent write corruption
## What cross-agent looks like
**Session 1** (Claude Code):
> "Remember: the freee API returns dates in JST, not UTC. Our conversion layer is in `src/utils/date.ts`."
**Session 2** (Cursor, different project window):
> "I'm building a freee integration. What do I need to know?"
Cursor calls `recall("freee")` and gets:
* The JST date caveat
* The `date.ts` file location
* Any other freee-related memories from any agent
## Supported clients
Any client implementing the [MCP specification](https://modelcontextprotocol.io) works:
| Client | Status |
| ---------------- | ----------------------- |
| Claude Code | Full support |
| Claude Desktop | Full support |
| Cursor | Full support |
| Windsurf | Full support |
| Cline | Full support |
| OpenAI Codex CLI | Full support (MCP mode) |
| Gemini CLI | Full support (MCP mode) |
Linksee Memory is a standard **stdio MCP server**. If a client speaks MCP over stdio, it works. No special integration needed.
# Forgetting Curve
Source: https://docs.linksee.app/concepts/forgetting-curve
Ebbinghaus-inspired memory lifecycle — heat bands, decay, and protection
Not all memories should live forever. Linksee Memory uses an **Ebbinghaus-inspired forgetting curve** to naturally decay unimportant memories while permanently preserving critical ones.
## Heat bands
Every memory has a **heat score** (0-100) that decays over time since last access:
| Band | Heat range | Meaning |
| -------- | ---------- | ------------------------------------ |
| `hot` | 70-100 | Recently accessed, actively relevant |
| `warm` | 40-69 | Accessed within days, still relevant |
| `cold` | 10-39 | Not accessed recently, fading |
| `frozen` | 0-9 | Very old, candidate for forgetting |
Heat is computed using a decay function inspired by the Ebbinghaus forgetting curve — rapid initial decay that slows over time.
## Forgetting risk
When `forget` or `consolidate` runs, each memory gets a **forgetting risk** score:
```
risk = (1 - heat/100) × (1 - importance) × daysSinceAccess × (1 + daysSinceAccess/30) × altitudeMultiplier
```
### Risk thresholds
| Risk | Action |
| ------ | -------------------------------------------- |
| \< 50 | **Keep** — still valuable |
| 50-200 | **Compress** — merge into a learning summary |
| > 200 | **Drop** — safe to delete |
## What's always protected
Some memories **never decay**, regardless of heat or age:
| Category | Why |
| -------------------------- | ------------------------------------ |
| Caveat layer | Pain lessons must never be relearned |
| Goal layer | Direction must persist |
| Pinned (importance >= 0.9) | Explicitly marked as critical |
| Mission altitude | Foundational purpose never fades |
## Accessing refreshes heat
Every `recall` that returns a memory **bumps its heat** back up. This means:
* Frequently used memories stay hot naturally
* Important but rarely accessed memories can be pinned (`importance >= 0.9`) to prevent decay
* Truly forgotten memories fade gracefully
Use `recall` with `mark_accessed: false` for preview queries that shouldn't affect heat scores.
## Consolidation lifecycle
```mermaid theme={null}
graph LR
H[Hot memory] -->|time passes| W[Warm]
W -->|more time| C[Cold]
C -->|consolidate| L[Learning summary]
C -->|forget sweep| D[Deleted]
L -->|protected| L
```
Cold memories are candidates for `consolidate`, which clusters them by (entity, layer) and produces a single learning-layer summary. The originals are deleted, but the essential knowledge is preserved in compressed form.
# Memory Layers
Source: https://docs.linksee.app/concepts/memory-layers
The 6-layer structure that separates Linksee from flat memory stores
Most agent memory systems store everything in a flat list. Linksee Memory organizes memories into **6 cognitive layers**, each with different retention and retrieval behavior.
## The 6 layers
```mermaid theme={null}
graph TB
G[goal] --> C[context]
C --> E[emotion]
E --> I[implementation]
I --> CA[caveat]
CA --> L[learning]
style G fill:#059669,color:#fff
style CA fill:#dc2626,color:#fff
style L fill:#6366f1,color:#fff
```
**WHY this work exists.** The target outcome. Persists across sessions so the agent doesn't drift.
* Never auto-forgotten (risk = 0)
* Set at session start or when the user states a new objective
* Example: *"Ship v1.0 by end of Q2 with cross-agent recall and token-saving"*
**WHY THIS, NOW.** Situational timing, background info, reasons for current priorities.
* Normal decay rate
* Consolidated after going cold
* Example: *"Vercel had a security incident in April — rotating all API keys across projects"*
**User tone and sentiment.** Frustration, excitement, urgency expressed during work.
* Normal decay rate
* Helps agents calibrate tone in future sessions
* Example: *"User frustrated with freee API pagination — 3 sessions debugging"*
**HOW it was done.** What worked, what failed, technical details of execution.
* Normal decay rate
* Most common layer for day-to-day memories
* Example: *"Switched from REST to GraphQL for freee sync — 3x faster batch queries"*
**PAIN lessons.** "Never X when Y." The protected pile of things you don't want to relearn.
* **Always protected** — never auto-forgotten, never consolidated
* Start with a verb: "Never", "Always", "Watch out"
* Example: *"Never use pgbouncer session mode with Supabase — prepared statement conflicts"*
**GROWTH.** Decisions made, insights gained, patterns recognized.
* Normal decay rate but typically higher importance
* Target layer for consolidation output
* Example: *"freee webhook reliability is \~95% — always implement polling fallback"*
## Layer aliases
You don't need to remember exact layer names. Common aliases are automatically resolved:
| You say | Stored as |
| --------------------------------------------- | ---------------- |
| `why`, `intent`, `targets` | `goal` |
| `background`, `reason`, `situation`, `timing` | `context` |
| `tone`, `feelings`, `mood` | `emotion` |
| `impl`, `how`, `tried`, `success`, `failure` | `implementation` |
| `warning`, `pain`, `pitfall`, `dont`, `rule` | `caveat` |
| `decision`, `insight`, `growth`, `learned` | `learning` |
## Retention behavior
| Layer | Auto-forget | Consolidation target | Protection |
| ---------------- | ----------- | -------------------- | ---------- |
| `goal` | Never | No | Implicit |
| `context` | Normal | Yes → `learning` | No |
| `emotion` | Normal | Yes → `learning` | No |
| `implementation` | Normal | Yes → `learning` | No |
| `caveat` | Never | No | Always |
| `learning` | Normal | No (already target) | No |
## Why layers matter
Without layers, `recall("Supabase")` returns a wall of undifferentiated text. With layers, the agent can:
* Start with `goal` to understand direction
* Check `caveat` before making changes
* Skim `implementation` for prior approaches
* Use `learning` for distilled wisdom
This is the difference between "I read my notes" and "I understand my history."
# Product map & drift
Source: https://docs.linksee.app/concepts/product-map
A map.yaml describes how value reaches your user; where_am_i and the linksee-memory map CLI navigate it and catch drift.
## The idea
Memory records *what you decided*. A **product map** records *how those decisions reach the user* — discover → understand → try → adopt → retain → monetize → expand — with typed dependencies between the pieces (README, npm listing, onboarding, the engine behind them). Reconciling the two against the actual code is just a diff, with file:line evidence. That diff is drift detection.
## `where_am_i` (MCP tool)
The per-turn re-anchor. Given a topic, a node id, or **no arguments at all** (it infers from your recent edits), it locates you on the map and returns the **blast radius** — what else becomes suspect if you change this. Editing the README implicates the LP and the docs; `where_am_i` grades how strongly: `must fix together` vs `should align` vs `fyi`.
## `linksee-memory map` (CLI)
`map.yaml` (repo root) is the desired-state source of truth — git-tracked and reviewable. The CLI answers the questions an engineer actually has:
```bash theme={null}
npx -y linksee-memory map where README.md # where am I, and what does this file touch?
npx -y linksee-memory map explain readme # why this state? — declared vs reality, with file:line evidence
npx -y linksee-memory map status # whole-project health + what needs attention
npx -y linksee-memory map reconcile # re-check the map against the real code/files
```
Example — a README that documents an `--export` flag the code never implemented:
```
$ npx -y linksee-memory map explain readme
STATUS reality: drifted
EVIDENCE ✓ README documents the --export flag README.md:11
✗ src/cli.js implements --export not found
FIX implement --export, or drop the claim
AFFECTS docs-site, cli-engine (must fix together)
```
It isn't grep: the map knows the dependencies, grades their strength, and shows the evidence. Add `--lang ja` for Japanese labels. Other commands: `affects`, `next`, `inspect --json`, `blueprint`.
## How a verdict is decided
Each map node can declare how to verify itself from reality — a `signal` / `regex` / `section_contains` / file check. The reconciler runs it and overlays a verdict (**convergence** / **divergence**) that overrides the hand-declared status. An "accounted-for" drift (deferred on purpose) must carry an expiry or release condition, so it can't quietly become a drift graveyard.
# 3-Axis Classification
Source: https://docs.linksee.app/concepts/three-axis
Altitude, Type, and State — queryable dimensions on every memory
Every memory in Linksee is auto-classified along **3 orthogonal axes** when stored. These are stored as queryable virtual columns, enabling precise filtering in `recall`.
## Axis 1: Altitude (cognitive level)
How high-level is this thought?
| Altitude | Description | Forgetting multiplier |
| ---------------- | ------------------------------ | --------------------- |
| `mission` | Why we exist | **0** (never decays) |
| `strategy` | Positioning, GTM, roadmap | 0.1 (very slow) |
| `architecture` | System design, tech choices | 0.3 (slow) |
| `implementation` | Code, tasks, execution details | 1.0 (normal) |
Altitude affects forgetting speed. A mission-level memory about why the company exists will never auto-decay, while an implementation detail about a specific API call will fade naturally.
## Axis 2: Type (what kind of thought)
What is this memory, cognitively?
| Type | Description | Example |
| ------------ | ------------------------- | ---------------------------------------------------------------------- |
| `question` | An open question | "Should we use REST or GraphQL for the sync layer?" |
| `comparison` | Evaluating alternatives | "freee vs MoneyForward — freee has better API docs but worse webhooks" |
| `decision` | A choice that was made | "Going with PostgreSQL over MySQL for the main database" |
| `work` | Work in progress | "Implementing the token-saving diff cache for read\_smart" |
| `outcome` | Result of completed work | "Deployed v0.5.0 — all tests passing, 3 beta users onboarded" |
| `learning` | Insight or lesson learned | "FTS5 trigram tokenizer handles Japanese better than unicode61" |
| `note` | General note | "Team standup moved to Tuesdays" |
## Axis 3: State (lifecycle)
Where is this thought in its lifecycle?
| State | Description |
| ------------- | ---------------------------------------- |
| `open` | Not yet resolved |
| `decided` | Decision made, not yet implemented |
| `in_progress` | Currently being worked on |
| `done` | Completed |
| `stalled` | In-progress but untouched for 30+ days |
| `parked` | Deliberately set aside for later |
| `superseded` | Replaced by a newer decision or approach |
`consolidate` automatically marks `in_progress` memories untouched for 30+ days as `stalled`.
## Using axes in recall
Filter by any combination of axes:
```json theme={null}
{
"query": "database",
"altitude": "architecture",
"mem_type": "decision",
"mem_state": "decided"
}
```
This returns only architecture-level decisions about databases that have been decided — perfect for understanding why the current tech stack was chosen.
### Practical filter patterns
| I want to find... | Filter |
| ---------------------- | ------------------------------------------------ |
| Open questions | `mem_state: "open", mem_type: "question"` |
| Architecture decisions | `altitude: "architecture", mem_type: "decision"` |
| Stalled work | `mem_state: "stalled"` |
| Strategic insights | `altitude: "strategy", mem_type: "learning"` |
| Implementation details | `altitude: "implementation", mem_type: "work"` |
## Auto-inference
When you call `remember`, the 3 axes are **automatically inferred** from the content. You don't need to set them manually — but you can override by including structured JSON in the `content` field.
# Token Saving
Source: https://docs.linksee.app/concepts/token-saving
How read_smart saves 50-99% tokens with AST-aware file diff caching
Every token costs money and context window space. `read_smart` is an MCP tool that caches file content and returns **only what changed** — saving 50-99% tokens on re-reads.
## The problem
A typical agent session reads the same files multiple times:
1. Read `src/index.ts` to understand the codebase (900 tokens)
2. Make changes
3. Read `src/index.ts` again to verify (900 tokens)
4. Read it again after another change (900 tokens)
**2,700 tokens** for one file, but the content barely changed between reads.
## The solution
`read_smart` maintains a **per-file snapshot** with content hashes:
| Read | Status | Tokens | Savings |
| ------------------------ | ----------------------------- | --------- | ------------------ |
| 1st | `first_read` — full content | 900 | — |
| 2nd (no change) | `unchanged` — chunk list only | 50 | **94%** |
| 3rd (1 function changed) | `modified` — diff only | 200 | **78%** |
| 4th (no change) | `unchanged` | 50 | **94%** |
| **Total** | | **1,200** | **vs 3,600 naive** |
## AST-aware chunking
Unlike line-based diffing, `read_smart` splits files into **semantic chunks**:
### TypeScript / JavaScript
Parsed via `@babel/parser` into top-level declarations:
```
chunk: "createPool" (lines 7-25)
chunk: "getConnection" (lines 27-45)
chunk: "closePool" (lines 47-55)
```
If you add a new function at line 7, only that new chunk is "changed" — `getConnection` and `closePool` keep their identity (even though their line numbers shifted).
### Python
Split by top-level `def` and `class` blocks using indentation analysis.
### Markdown
Split by `h2` and `h3` headings.
### Other files
Fixed 100-line windows.
## Token estimation
Token count is estimated at **0.3 tokens per character** — a blended rate that works for both English and Japanese text.
## Cache storage
Snapshots are stored in the `file_snapshots` table in the same SQLite database as memories. No external services required.
| Column | Purpose |
| -------------- | ------------------------------------------------- |
| `path` | Absolute file path |
| `mtime_ms` | Last modification time |
| `sha256` | Full file hash |
| `chunks_json` | Array of chunk definitions with individual hashes |
| `total_tokens` | Estimated token count |
# Installation
Source: https://docs.linksee.app/installation
Install Linksee Memory and connect it to your MCP client
## Install
The fastest path — one command sets up the MCP server, the skill, and the auto-capture hook:
```bash theme={null}
npx -y linksee-memory setup
```
Requires **Node.js 20+**. Check your version with `node --version`.
Prefer to wire it up by hand? Install globally and add the config for your client below:
```bash theme={null}
npm install -g linksee-memory
```
## Configure your MCP client (manual)
Add Linksee Memory to your client's MCP server configuration.
Run the built-in installer:
```bash theme={null}
npx -y linksee-memory install-skill
```
Or add manually to your Claude Code MCP settings:
```json theme={null}
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory"
}
}
}
```
Edit `claude_desktop_config.json`:
```json macOS theme={null}
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory"
}
}
}
```
```json Windows theme={null}
// %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory"
}
}
}
```
Add to your MCP configuration file (usually `.cursor/mcp.json` or equivalent):
```json theme={null}
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory"
}
}
}
```
Linksee Memory uses **stdio transport**. Any MCP client that supports stdio can connect:
```json theme={null}
{
"command": "linksee-memory",
"transport": "stdio"
}
```
## Verify the installation
After restarting your agent, try:
> "Use linksee to remember that I prefer TypeScript over JavaScript"
The agent should call the `remember` tool and confirm the memory was stored.
Then in a **new session**:
> "What do I prefer, TypeScript or JavaScript? Check linksee."
The agent should call `recall` and find your preference.
## Database location
By default, the SQLite database is stored at:
| OS | Path |
| ------------- | ----------------------------------------- |
| macOS / Linux | `~/.linksee-memory/memory.db` |
| Windows | `%USERPROFILE%\.linksee-memory\memory.db` |
Override with the `LINKSEE_MEMORY_DIR` environment variable:
```bash theme={null}
LINKSEE_MEMORY_DIR=/path/to/custom/dir linksee-memory
```
Or in your MCP config:
```json theme={null}
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory",
"env": {
"LINKSEE_MEMORY_DIR": "/path/to/custom/dir"
}
}
}
}
```
## Uninstall
```bash theme={null}
npm uninstall -g linksee-memory
```
Your memory database at `~/.linksee-memory/memory.db` is preserved. Delete it manually if you want a clean slate.
# Introduction
Source: https://docs.linksee.app/introduction
A local-first memory layer for coding agents — tied to a product map that catches when your README, docs, and code drift apart.
## What is Linksee Memory?
Linksee Memory is a **local-first MCP server** that gives every AI agent on your machine persistent, structured memory — and ties that memory to a **product map**, so it can also catch when your README, docs, and code quietly drift apart.
Sessions end. Agents forget. You're juggling several projects, and so is your agent. Linksee Memory fixes the forgetting — then uses the same memory + map to catch drift, with file:line evidence.
Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI — one memory, all agents.
`where_am_i` + the `linksee-memory map` CLI locate any file on your map and report its blast radius.
Reconcile what you decided against the actual code — convergence / divergence with evidence.
No cloud. No account. No network calls. One SQLite file on your machine.
## Quick Start
One command sets up the MCP server, the skill, and the auto-capture hook:
```bash theme={null}
npx -y linksee-memory setup
```
Restart your agent. Done. (Prefer manual config? See [Installation](/installation).)
Works with **any MCP-compatible client** — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and more.
## Key Features
* **11 MCP tools** — memory (`remember`, `recall`, `read_smart`), drift (`drift_status`, `declare_anchor`, `check_decision`, `resolve_drift`, `flag_proposals`, `resolve_proposal`, `dream`), and **`where_am_i`** — locate the current file on your product map + its blast radius.
* **`linksee-memory map` CLI** — `where` · `affects` · `explain` · `status` · `next` · `reconcile` · `inspect --json` · `blueprint`. A `map.yaml` (git source of truth) describes how value reaches your user; the reconciler checks it against your code. Bilingual via `--lang ja`.
* **6-layer structured memory** — goal / context / emotion / implementation / caveat / learning, with an Ebbinghaus forgetting curve (caveats and goals protected forever).
* **AST-aware token-saving reads** — `read_smart` returns only changed chunks (50–99% fewer tokens on re-reads).
* **Local-first & bilingual** — one SQLite file, no network, full Japanese + English (trigram FTS5).
## How It Works
1. **During a session**, the agent calls `remember` to store decisions, caveats, and context.
2. **On the next session**, `recall` retrieves relevant memories ranked by relevance, heat, and importance.
3. **Across the product**, a `map.yaml` records how those decisions reach the user; `reconcile` checks the map against the actual code and flags drift with file:line evidence.
4. **Anytime**, `where_am_i` tells the agent where it is on the map and what else a change would touch.
## System Requirements
* Node.js 20+
* Any MCP-compatible client
* \~10 MB disk space for the SQLite database
## Next Steps
Detailed setup for every MCP client
Your first remember → recall flow in 2 minutes
where\_am\_i, the map CLI, and how drift detection works
Understand the 6-layer structure
# entity-handoff
Source: https://docs.linksee.app/prompts/entity-handoff
Produce a handoff document for transferring context to a new session or agent
Produce a **handoff document** for an entity: name, kind, key memories per layer, current open questions, and next steps. Use when transferring context to a new session, a new agent, or a new collaborator.
## Arguments
The entity to hand off.
Who receives the handoff. Examples: "new claude session", "human teammate", "cursor agent".
## Output format
Markdown document with sections:
1. **Identity** — entity name, kind, canonical key
2. **Goal** — current objectives
3. **State** — where things stand
4. **Caveats** — with `memory_id` citations
5. **Open questions** — unresolved items
6. **Suggested next steps** — actionable recommendations
Kept under 1 page for readability.
## Workflow
1. Call `recall` with `max_tokens: 6000` for the entity
2. Group returned memories by layer
3. Synthesize into the handoff document format
# extract-caveats
Source: https://docs.linksee.app/prompts/extract-caveats
Scan text for pain lessons and propose caveat-layer memories
Scan a body of text (post-mortem, error log, decision doc) and propose **caveat-layer memories** — concise pain lessons starting with verbs.
## Arguments
Source text. Post-mortem, debug session transcript, retro notes, or any text containing lessons learned.
Optional canonical entity name for the caveats.
## Output format
```json theme={null}
[
{
"content": "Never deploy freee OAuth changes on Friday — sandbox goes down for maintenance every Friday night JST",
"importance": 0.9
},
{
"content": "Always check Supabase connection pool limits before adding new services — default is 20 connections",
"importance": 0.85
}
]
```
## Caveat writing rules
Each caveat must:
* **Start with a verb**: "Never", "Always", "Watch out", "Check", "Verify"
* **Be one sentence** — concise and actionable
* **Be concrete** — include specific names, numbers, conditions
* **Capture something painful** — things the reader does NOT want to relearn
# Prompts Overview
Source: https://docs.linksee.app/prompts/overview
5 built-in MCP prompts for common memory workflows
Linksee Memory includes **5 MCP prompts** — reusable workflow templates that guide the agent through structured memory operations.
## Available prompts
Extract structured memories from a session transcript. Up to 6 memories (one per layer).
Scan text for pain lessons and propose caveat-layer memories.
Anti-pattern guard: recall before acting, cite memory IDs in output.
Produce a handoff document for transferring context to a new session or agent.
Summarize a week's memories into a single learning-layer entry.
## How prompts work
MCP prompts are templates that the agent expands with arguments. In Claude Code, invoke them via the prompts list or by asking the agent to use them:
> "Use the summarize-session prompt to capture what we did today"
The agent fills in the template arguments and executes the workflow.
# recall-and-write
Source: https://docs.linksee.app/prompts/recall-and-write
Anti-pattern guard — recall before acting, cite memory IDs in output
Anti-pattern guard. Before writing code, drafting a doc, or making a decision: **recall relevant memories first**, then produce the answer with explicit citations to recalled memory IDs.
Forces "memory before action" discipline.
## Arguments
What you are about to do. One sentence describing the code task, decision, or document draft.
Optional entity to focus recall on.
## Workflow
1. Call `recall` with the task description
2. Skim returned memories and identify applicable caveats
3. Produce output with inline citations: `[memory:1234]`
4. If no relevant memories found, state explicitly: "No prior context found"
## Why this matters
Without this prompt, agents tend to act first and recall later (or not at all). This creates:
* Repeated mistakes that caveats could have prevented
* Inconsistent decisions across sessions
* Wasted tokens re-discovering known constraints
The recall-and-write pattern ensures every significant action is informed by prior context.
# summarize-session
Source: https://docs.linksee.app/prompts/summarize-session
Extract structured memories from a session transcript
Turn a chat session transcript into structured memories. Produces up to **6 memories** (one per layer) capturing goal / context / emotion / implementation / caveat / learning.
Use at session end to preserve the most valuable parts of the conversation.
## Arguments
The session transcript text. Free-form — paste the conversation or a summary.
Optional canonical entity name to attach the memories to (e.g. "MyProject"). If omitted, the prompt infers entities from the transcript.
## What it produces
A JSON array of memory objects ready for `remember`:
```json theme={null}
[
{
"entity_name": "KanseiLink",
"entity_kind": "project",
"layer": "goal",
"content": "Ship AEO report generation by end of May",
"importance": 0.8
},
{
"entity_name": "KanseiLink",
"entity_kind": "project",
"layer": "caveat",
"content": "Never cache freee OAuth tokens longer than 1 hour — they silently expire",
"importance": 0.95
}
]
```
## Rules
* Maximum 6 entries (one per layer)
* Importance scored 0.0 to 1.0
* Caveats must be 1 sentence starting with a verb
* No verbatim quotes from the transcript
* Focus on decisions, pain, and insights — skip routine actions
# weekly-consolidation
Source: https://docs.linksee.app/prompts/weekly-consolidation
Summarize the past week's memories into a learning-layer entry
Sleep-mode summary of the past week's memories for an entity. Produces a single **learning-layer entry** that captures the trajectory. Use as input to the `consolidate` tool, or to write a Friday digest.
## Arguments
The entity to consolidate.
Weeks-ago offset. `0` = this week, `1` = last week.
## Workflow
1. Call `recall` for the entity, filtered to the target week
2. Produce a learning-layer summary covering:
* Goal trajectory (progress toward objectives)
* What happened (key events, decisions)
* Insights gained
* Caveats to preserve
3. Output a JSON memory object: `{entity_name, layer: "learning", content, importance: 0.7}`
## When to use
* **Friday wrap-up**: Run at the end of each week to compress the week's work
* **Before consolidation**: Generate the summary, then run `consolidate` to clean up cold memories
* **Monthly reviews**: Run with `week_offset: 1` through `4` to review the past month
# Quick Start
Source: https://docs.linksee.app/quickstart
Your first remember → recall flow in 2 minutes
## The basic flow
Linksee Memory has one core loop: **remember → recall → act**.
```mermaid theme={null}
graph LR
A[Session 1] -->|remember| B[(Memory)]
B -->|recall| C[Session 2]
C -->|remember| B
```
## Step 1: Remember something
In any conversation with your AI agent, say:
> "Remember that our production database is PostgreSQL 16 on Supabase, and we had a connection pooling issue last week that was fixed by switching to transaction mode."
The agent calls `remember` and stores this as structured memory:
* **Entity**: your project name
* **Layer**: `implementation` (how it was done)
* **Content**: the PostgreSQL + pooling fix details
You can also say **"use linksee"** or **"don't forget this"** to trigger memory storage.
## Step 2: Add a caveat
Caveats are the most valuable layer — pain lessons that should never be forgotten:
> "Linksee caveat: Never use pgbouncer in session mode with Supabase — it causes prepared statement conflicts. Always use transaction mode."
This gets stored in the **caveat layer** with `protected = true` — it will never be auto-forgotten.
## Step 3: Recall in a new session
Start a fresh session. Ask:
> "I'm about to set up a new Supabase project. What do I need to know? Check linksee."
The agent calls `recall` and returns your memories, ranked by relevance:
```json theme={null}
{
"memories": [
{
"id": 42,
"layer": "caveat",
"content": "Never use pgbouncer in session mode with Supabase...",
"importance": 0.95,
"match_reasons": ["content_match_fts", "caveat_protected", "heat:hot"]
},
{
"id": 41,
"layer": "implementation",
"content": "Production database is PostgreSQL 16 on Supabase...",
"importance": 0.6,
"match_reasons": ["content_match_fts", "entity_name_match"]
}
]
}
```
The caveat surfaces first because it's protected and highly important.
## Step 4: Use read\_smart for files
When re-reading a file you've seen before:
> "Read src/db/connection.ts using linksee read\_smart"
First read returns full content. On subsequent reads, if the file hasn't changed, you get:
```json theme={null}
{
"status": "unchanged",
"chunks": [
{ "name": "createPool", "hash": "a1b2c3...", "lines": "1-25" },
{ "name": "getConnection", "hash": "d4e5f6...", "lines": "27-45" }
],
"tokens_saved": "~850 (was ~900, now ~50)"
}
```
**\~95% token savings** on unchanged files.
## What to remember
Not everything needs to be memorized. Focus on:
| Worth remembering | Skip |
| ------------------------------- | ------------------------------ |
| Decisions and why you made them | Routine code changes |
| Pain lessons and gotchas | Temporary debug output |
| Architecture choices | One-off questions |
| User preferences | Content that's already in docs |
| Project-specific conventions | Generic knowledge |
The `summarize-session` prompt can automatically extract the right memories from a session transcript. Use it at the end of important sessions.
## Next steps
Understand goal / context / emotion / implementation / caveat / learning
How read\_smart saves 50-99% tokens with AST-aware diffing
Full parameter docs for all 11 tools
5 built-in prompts for common workflows
# Architecture
Source: https://docs.linksee.app/reference/architecture
Database schema, tables, and internal design
## Overview
Linksee Memory is a single-process Node.js MCP server using **SQLite** (via `better-sqlite3`) with WAL mode for concurrent read access.
```mermaid theme={null}
graph TB
subgraph MCP Server
H[Tool Handlers]
R[Resource Handlers]
P[Prompt Handlers]
end
subgraph SQLite DB
E[entities]
M[memories]
FTS[memories_fts]
FS[file_snapshots]
FF[file_facts]
S[sessions]
SFE[session_file_edits]
EV[events]
ED[edges / memory_edges]
CO[consolidations]
end
H --> E
H --> M
H --> FS
R --> M
M --> FTS
```
## Database tables
### Core tables
| Table | Purpose |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `entities` | People, companies, projects, concepts, files with normalized dedup and momentum cache |
| `memories` | 6-layer structured memories with importance, protected flag, thread\_id, and 3 virtual generated columns |
| `memories_fts` | FTS5 virtual table with trigram tokenizer for full-text search (supports CJK) |
### Relationship tables
| Table | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `memory_edges` | Directed relationships between memories (supersedes, resolves, implements, contradicts, extends) |
| `edges` | Entity-to-entity graph relationships |
### File tracking
| Table | Purpose |
| -------------------- | -------------------------------------------------------------------------- |
| `file_snapshots` | Diff cache for `read_smart` — per-file content snapshots with chunk hashes |
| `file_facts` | Extracted facts per file chunk |
| `sessions` | Agent/conversation tracking |
| `session_file_edits` | Conversation-to-file linkage with `context_snippet` |
### Lifecycle
| Table | Purpose |
| ---------------- | -------------------------------------------- |
| `events` | Time-series log driving momentum calculation |
| `consolidations` | Audit trail of what got compressed into what |
| `meta` | Schema version tracking (currently v7) |
## Virtual generated columns
The `memories` table has 3 virtual columns auto-extracted from structured JSON content:
```sql theme={null}
altitude TEXT GENERATED ALWAYS AS (json_extract(content, '$.altitude'))
mem_type TEXT GENERATED ALWAYS AS (json_extract(content, '$.type'))
mem_state TEXT GENERATED ALWAYS AS (json_extract(content, '$.state'))
```
These enable SQL-level filtering without parsing JSON at query time.
## FTS5 configuration
```sql theme={null}
CREATE VIRTUAL TABLE memories_fts USING fts5(
content,
content=memories,
content_rowid=id,
tokenize='trigram'
);
```
The trigram tokenizer handles both English and Japanese text without language-specific stemming.
## SQLite pragmas
```sql theme={null}
PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
```
WAL mode allows concurrent reads from multiple MCP clients while maintaining write safety.
# Changelog
Source: https://docs.linksee.app/reference/changelog
Version history and release notes
## v0.11.3
**Robustness + MCP hygiene** — 2026-06-16
* **Corrupt-DB recovery:** an unreadable memory DB is preserved as `memory.db.corrupt-` and a fresh one is created, instead of crashing with a raw SQLite error.
* **`recall`** tool description no longer nudges editing the system prompt.
## v0.11.2
**More cold-start hardening** — 2026-06-16
* **`stats`** works on a fresh database instead of crashing with `no such table` (it ensures the schema exists first).
* **`map --help`** prints usage instead of importing a map.
## v0.11.1
**Cold-start fixes** — 2026-06-16
* **Run any CLI through the package name:** `npx -y linksee-memory setup` (and `map`, `sync`, `guard`, `stats`, `import`, `install-skill`). A fresh user couldn't reach the standalone bins (`linksee-memory-setup`, …) with `npx` — npx resolves package names, not sibling bin names. The main bin now dispatches subcommands; the standalone bins remain as aliases.
* **`map` exits gracefully** with a next-step message when no `map.yaml` exists yet (was a raw stack trace).
* **serverInfo** reports the real package version (was pinned to an old string).
## v0.11.0
**The Map: `where_am_i` + `linksee-memory map`** — 2026-06-15
Memory is the entry point; the product map is the new surface.
* **`where_am_i`** (11th MCP tool) — locate the current file/topic on the Current Truth Map and get its blast radius (no args → infer from your recent edits).
* **`linksee-memory map`** CLI — `where` · `affects` · `explain` · `status` · `next` · `reconcile` · `inspect --json` · `blueprint`. A git-tracked `map.yaml` checked against your code with file:line evidence. Bilingual (`--lang ja`).
* Graded blast radius (`must fix together` / `should align` / `fyi`), declared-vs-reality verdicts, anti-graveyard expiry for accounted-for drift, and per-project keys for juggling many projects. See [Product map & drift](/concepts/product-map).
## v0.8.0
**Drift Detection MCP Tools** — 2026-06-08
`drift_status`, `check_decision`, `declare_anchor`, `resolve_drift` — agents can detect, query, and resolve intent ↔ reality drift, with a 4-species truth map.
## v0.7.1
**Review Fixes** — 2026-05-29
Based on Opus 4.7 design review of v0.7.0:
* **Required params guidance**: `remember` tool description now includes "REQUIRED PARAMS BY MODE" section so LLMs know exactly which fields are needed for create vs update vs delete
* **Migration guidance**: Deprecated tool names (`forget`, `recall_file`, etc.) return specific migration examples instead of generic errors
* **recall path+query merge**: When both `path` and `query` are provided to `recall`, results from file history and memory search are merged
* **Auto-consolidate safety**: Table existence check via `sqlite_master` before querying `consolidations` table, preventing errors on fresh databases
## v0.7.0
**3-Tool Unified Surface** — 2026-05-29
8 tools unified into 3 for cross-LLM consistency, following Context7's proven pattern.
**Breaking change**: The following tools are removed from the MCP surface:
| Old tool | New equivalent |
| --------------- | ----------------------------------------------- |
| `forget` | `remember({ forget: true, memory_id: })` |
| `update_memory` | `remember({ memory_id: , content: "..." })` |
| `recall_file` | `recall({ path: "server.ts" })` |
| `list_entities` | `recall({})` (no params = entity overview) |
| `consolidate` | Auto-runs on server startup (7-day threshold) |
**New unified tools:**
* **`remember`** — create + update + delete in one tool. Mode inferred from params
* **`recall`** — search + file history + overview in one tool. Mode inferred from params
* **`read_smart`** — unchanged
**Other changes:**
* Auto-consolidate on server startup (non-blocking, 7-day threshold)
* Claude Code Plugin bundle (`claude plugin add -- linksee-memory`)
* Deprecated tool names return migration guidance with examples
## v0.6.0
**3-Axis Memory** — 2026-05
* **3-axis classification**: Every memory auto-classified by altitude (mission/strategy/architecture/implementation), type (question/decision/work/outcome/...), and state (open/decided/in\_progress/done/stalled/...)
* **Virtual generated columns**: `altitude`, `mem_type`, `mem_state` are SQL-queryable without JSON parsing
* **Recall filters**: Filter by `altitude`, `mem_type`, `mem_state`, `thread_id`, and `band` in recall queries
* **Stalled detection**: `consolidate` auto-marks `in_progress` memories untouched for 30+ days as `stalled`
* **Thread support**: Group related memories via `thread_id` for decision chain tracing
* **Quality check**: `remember` rejects pasted CI logs and assistant output (bypass with `force: true`)
* **LLM-assisted consolidation**: `consolidate` with `use_llm: true` uses MCP Sampling for better summaries
* **Interactive forget**: `forget` with `interactive: true` uses MCP Elicitation for user confirmation
* **Roots-scoped recall\_file**: `scope_to_roots: true` filters to the client's working directories
## v0.5.0
**Token-Saving Engine** — 2026-04
* **read\_smart**: AST-aware file diff caching with 4 response statuses
* **AST chunking**: TS/JS/Python files split by function/class, Markdown by headings
* **Chunk identity**: Stable across reads — adding a function doesn't invalidate other chunks
* **file\_facts**: Extracted facts per file chunk
## v0.4.2
**Precision Memory** — 2026-04
* **Ebbinghaus forgetting curve**: Heat-based memory decay with altitude multipliers
* **Momentum scoring**: Entity activity frequency drives ranking
* **Consolidation**: Sleep-mode compression of cold memories into learning summaries
* **recall\_file**: File edit history with user-intent context
* **session\_file\_edits**: Every physical edit linked to conversation context
## v0.3.0
**Cross-Agent Foundation** — 2026-03
* **6-layer memory structure**: goal / context / emotion / implementation / caveat / learning
* **FTS5 trigram search**: Full-text search supporting English and Japanese
* **Entity dedup**: 3-tier matching (canonical\_key / normalized\_name / case-insensitive)
* **Caveat protection**: Caveat-layer memories permanently preserved
* **Pinning**: importance >= 0.9 protects from auto-forgetting
## v0.2.0
**Initial Release** — 2026-02
* Basic remember/recall with SQLite storage
* Entity-based memory organization
* MCP stdio transport
# CLI Commands
Source: https://docs.linksee.app/reference/cli
Command-line utilities included with linksee-memory
The `linksee-memory` npm package includes several CLI utilities beyond the MCP server itself.
Each CLI is reachable two ways: as a subcommand via `npx -y linksee-memory ` (no install needed — the package name resolves on a cold machine), and, if `linksee-memory` is installed on your PATH, as the standalone `linksee-memory-` bin (e.g. `linksee-memory-setup`). The runnable examples below use the cold-safe `npx -y linksee-memory ` form.
## linksee-memory
The main MCP server. Runs in **stdio mode** — typically launched by your MCP client, not directly.
```bash theme={null}
npx -y linksee-memory
```
## linksee-memory setup
Interactive initial setup. Creates the database directory and initializes the schema.
```bash theme={null}
npx -y linksee-memory setup
```
## linksee-memory install-skill
Install the Linksee Memory skill into Claude Code's MCP configuration.
```bash theme={null}
npx -y linksee-memory install-skill
```
## linksee-memory stats
Display database statistics: entity count, memory count, layer breakdown, heat distribution, database size.
```bash theme={null}
npx -y linksee-memory stats
```
Example output:
```
Linksee Memory Stats
====================
Entities: 24
Memories: 186
goal: 12
context: 34
emotion: 8
implementation: 78
caveat: 22
learning: 32
Heat bands:
hot: 15
warm: 42
cold: 89
frozen: 40
File snapshots: 67
DB size: 4.2 MB
```
## linksee-memory import
Import session transcripts or external data into the memory store.
```bash theme={null}
npx -y linksee-memory import
```
## linksee-memory sync
Sync a session's data. Useful for manual synchronization after disconnects.
```bash theme={null}
npx -y linksee-memory sync
```
# Configuration
Source: https://docs.linksee.app/reference/configuration
Environment variables and runtime options
## Environment variables
| Variable | Default | Description |
| -------------------- | ------------------- | -------------------------------------- |
| `LINKSEE_MEMORY_DIR` | `~/.linksee-memory` | Directory for the SQLite database file |
The database file is always named `memory.db` inside the configured directory.
## MCP client configuration
### Basic setup
```json theme={null}
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory"
}
}
}
```
### Custom database location
```json theme={null}
{
"mcpServers": {
"linksee-memory": {
"command": "linksee-memory",
"env": {
"LINKSEE_MEMORY_DIR": "/path/to/custom/dir"
}
}
}
}
```
### Multiple instances
You can run separate memory stores for different contexts:
```json theme={null}
{
"mcpServers": {
"linksee-work": {
"command": "linksee-memory",
"env": {
"LINKSEE_MEMORY_DIR": "~/.linksee-memory/work"
}
},
"linksee-personal": {
"command": "linksee-memory",
"env": {
"LINKSEE_MEMORY_DIR": "~/.linksee-memory/personal"
}
}
}
}
```
## MCP capabilities
### Server declares
```json theme={null}
{
"tools": {},
"resources": { "subscribe": false, "listChanged": false },
"prompts": { "listChanged": false }
}
```
### Client capabilities used (optional)
| Capability | Used by | Fallback |
| ------------------------ | ----------------------------------------- | ----------------------- |
| `sampling/createMessage` | `consolidate` with `use_llm: true` | Heuristic summarization |
| `roots/list` | `recall_file` with `scope_to_roots: true` | No filtering |
| `elicitation/create` | `forget` with `interactive: true` | Skips confirmation |
All three degrade gracefully when the client does not support them.
# Resources Overview
Source: https://docs.linksee.app/resources/overview
MCP resources for browsing memory state without tool calls
Linksee Memory exposes **4 static resources** and **3 resource templates** via the MCP Resources protocol. Resources provide read-only views into the memory store — useful for IDE sidebar panels, dashboards, or quick inspection without making tool calls.
## Static resources
These are always available and return current state:
| URI | Description |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| [`memory://stats`](/resources/static#stats) | Summary counts: entities, memories, layer breakdown, heat distribution |
| [`memory://hot`](/resources/static#hot) | Memories currently in the "hot" heat band |
| [`memory://recent`](/resources/static#recent) | Memories accessed in the last 7 days |
| [`memory://caveats`](/resources/static#caveats) | Every caveat-layer memory — the protected "never forget" pile |
## Resource templates
Parameterized resources for drilling into specific data:
| URI Template | Description |
| ------------------------ | ------------------------------------ |
| `memory://entity/{name}` | All memories about a specific entity |
| `memory://layer/{layer}` | All memories in a specific layer |
| `memory://memory/{id}` | A single memory by its numeric ID |
## How to use
In MCP clients that support resource browsing (e.g. Claude Desktop's resource panel), these appear as browsable data sources. They return `application/json`.
In code, access via the MCP resources protocol:
```json theme={null}
{
"method": "resources/read",
"params": {
"uri": "memory://caveats"
}
}
```
# Static Resources
Source: https://docs.linksee.app/resources/static
4 always-available read-only views into memory state
## memory://stats
Summary statistics for the entire memory store.
```json theme={null}
{
"entities": 24,
"memories": 186,
"layers": {
"goal": 12,
"context": 34,
"emotion": 8,
"implementation": 78,
"caveat": 22,
"learning": 32
},
"heat_bands": {
"hot": 15,
"warm": 42,
"cold": 89,
"frozen": 40
},
"file_snapshots": 67,
"db_size_mb": 4.2
}
```
## memory://hot
Memories currently in the **hot** heat band (score 70-100). These are what the agent is actively working with.
Returns an array of memory objects sorted by heat score descending.
## memory://recent
Memories accessed in the **last 7 days**, ordered by most recent access. Useful for understanding what the agent has been working on across recent sessions.
## memory://caveats
Every **caveat-layer** memory — the permanently protected pile of pain lessons. These are the memories that should always be checked before making decisions.
Returns all caveats sorted by importance (highest first), then by recency.
Browse `memory://caveats` at the start of any significant work session to refresh your awareness of known pitfalls.
# Resource Templates
Source: https://docs.linksee.app/resources/templates
Parameterized resources for drilling into specific entities, layers, and memories
## memory://entity/
All memories about a specific entity. Replace `{name}` with the entity name.
```
memory://entity/KanseiLink
memory://entity/Supabase
memory://entity/Alice
```
Returns all memories for that entity, grouped by layer.
## memory://layer/
All memories in a specific layer across all entities. Replace `{layer}` with one of: `goal`, `context`, `emotion`, `implementation`, `caveat`, `learning`.
```
memory://layer/caveat
memory://layer/goal
```
Returns all memories in that layer, sorted by importance then recency.
## memory://memory/
A single memory by its numeric ID. Replace `{id}` with the `memory_id` from a `recall` response.
```
memory://memory/42
memory://memory/186
```
Returns the full memory object including all metadata, scores, and linked data.
# read_smart
Source: https://docs.linksee.app/tools/read-smart
Read files with diff-only caching — save 50-99% tokens on re-reads
Read a file with **diff-only caching**. Use INSTEAD of the standard `Read` tool for files you have read before — saves 50%+ tokens on re-reads.
## How it works
| Read # | File state | Response | Tokens |
| ------ | -------------------------------------------------- | --------------------------------------------------------------- | --------- |
| 1st | New file | Full content + chunk metadata | \~900 |
| 2nd | Unchanged (same mtime) | `"unchanged"` + cached chunk list | **\~50** |
| 2nd | Touched but identical (mtime changed, sha256 same) | `"unchanged_content"` | **\~50** |
| 2nd | Modified | Changed chunks with content + unchanged chunks as metadata-only | **\~200** |
## Parameters
Absolute file path.
If `true`, return full content regardless of cache state.
## Response statuses
### `first_read`
Full file content with chunk metadata. Each chunk includes:
* `name` — function name, heading text, or line range
* `hash` — sha256 of chunk content
* `lines` — line range in the file
### `unchanged`
File mtime matches cache. Returns chunk list (names + hashes) without content. **Maximum token savings.**
### `unchanged_content`
File mtime changed but sha256 matches — the file was touched (e.g. `git checkout`) but content is identical.
### `modified`
File actually changed. Returns:
* **Changed chunks**: full content included
* **Unchanged chunks**: metadata only (name + hash)
## Chunking strategies
| File type | Strategy | Chunk identity |
| ------------------- | --------------------- | ---------------------------------------------------------- |
| TS / JS / JSX / TSX | AST via @babel/parser | Top-level declarations (function name, class name, export) |
| Python | Indent-based | Top-level `def` / `class` blocks |
| Markdown | Heading-based | h2 / h3 sections |
| Everything else | Fixed windows | 100-line blocks |
AST-aware chunking means that if you add a function at the top of a file, only the new function shows as "changed" — existing functions keep their identity and hash, so they're returned as metadata-only.
## Example
```json theme={null}
{
"path": "/home/user/project/src/db/connection.ts"
}
```
First read:
```json theme={null}
{
"status": "first_read",
"chunks": [
{ "name": "import_block", "lines": "1-5", "hash": "abc123", "content": "import { Pool }..." },
{ "name": "createPool", "lines": "7-25", "hash": "def456", "content": "export function createPool()..." },
{ "name": "getConnection", "lines": "27-45", "hash": "ghi789", "content": "export async function..." }
],
"total_tokens": 890
}
```
Second read (unchanged):
```json theme={null}
{
"status": "unchanged",
"chunks": [
{ "name": "import_block", "lines": "1-5", "hash": "abc123" },
{ "name": "createPool", "lines": "7-25", "hash": "def456" },
{ "name": "getConnection", "lines": "27-45", "hash": "ghi789" }
],
"total_tokens": 48
}
```
**94.6% token savings.**
# recall
Source: https://docs.linksee.app/tools/recall
Search memories, get file history, or list entities — unified read tool
Your persistent memory across all AI tools. This is the **unified read tool** — it handles search, file history, and entity overview based on which parameters you provide.
**v0.7.0**: `recall` replaces the previous `recall` + `recall_file` + `list_entities` tools. Mode is auto-detected from params.
## Modes
### Search (provide `query`)
Returns memories ranked by a composite score of relevance, heat, momentum, and importance.
```json theme={null}
{
"query": "Supabase connection pooling",
"layer": "caveat",
"max_tokens": 3000
}
```
### File history (provide `path`)
Returns complete edit history of a file across all sessions, with per-edit user-intent context.
```json theme={null}
{
"path": "server.ts"
}
```
When both `path` and `query` are provided, results from file history and memory search are merged.
### Entity overview (no params)
Returns entity list sorted by momentum — the cheapest "what do I know?" primitive.
```json theme={null}
{}
```
## Parameters
### Search mode
What you want to remember. Free-text, entity name, or FTS5 MATCH expression.
Narrow results to a specific entity.
Filter by memory layer. Accepts aliases (e.g. `warnings` -> `caveat`).
Filter by cognitive altitude: `mission`, `strategy`, `architecture`, `implementation`.
Filter by memory type: `question`, `comparison`, `decision`, `work`, `outcome`, `learning`, `note`.
Filter by lifecycle state: `open`, `decided`, `in_progress`, `done`, `stalled`, `parked`, `superseded`.
Filter by thread ID — returns all memories in a decision chain or session group.
Filter by heat band: `hot`, `warm`, `cold`, `frozen`.
Approximate token budget. Iteration stops when this budget is consumed or `limit` is reached, whichever comes first.
Hard cap on number of memories returned.
Skip this many top results (pagination). Use `has_more` from prior response to decide next offset.
Set `false` for preview / listing queries that should not bump heat scores.
### File history mode
File path substring to match against edit history. Can be a filename (`search-services.ts`), partial path (`src/db/`), or full absolute path.
## Ranking (search mode)
Memories are ranked by a composite score:
```
score = 0.45 * relevance + 0.25 * heat + 0.15 * momentum + 0.15 * importance
```
| Factor | Weight | Source |
| ---------- | ------ | ---------------------------------- |
| Relevance | 45% | FTS5 BM25 score + LIKE match |
| Heat | 25% | Ebbinghaus decay since last access |
| Momentum | 15% | Entity activity frequency |
| Importance | 15% | User-assigned or auto-inferred |
## Response
### Search mode
Each memory in the response includes:
* `match_reasons` — array explaining why this memory ranked (e.g. `content_match_fts`, `entity_name_match`, `heat:hot`, `pinned`, `caveat_protected`)
* `score_breakdown` — individual scores for transparency
* `has_more` — boolean indicating if more results exist beyond the current page
* `stopped_by` — whether iteration stopped at `tokens`, `limit`, or `end`
### File history mode
| Field | Description |
| -------------------------- | ------------------------------------------------- |
| `paths_matched` | List of file paths that matched the substring |
| `total_edits` | Total number of physical edits recorded |
| `first_edit` / `last_edit` | Date range of edit history |
| `sessions_involved` | Number of distinct sessions that edited this file |
| `daily_breakdown` | Edits per day, grouped by operation type |
| `user_intents` | Distinct user-intent snippets, ordered by recency |
| `linked_memories` | Related memories with entity name and preview |
### Entity overview mode
Each entity includes: `name`, `kind`, `memory_count`, layer breakdown (`goal_count`, `caveat_count`, etc.), `momentum_score`.
**Dual search**: Recall uses both FTS5 full-text search (BM25-ranked, trigram tokenizer) and LIKE fallback, merging and deduplicating results. This ensures both exact and fuzzy matches are found, including Japanese text.
## Migration from pre-v0.7
| Old call | New equivalent |
| ---------------------------------------------- | ------------------------------------------ |
| `recall({ query: "..." })` | `recall({ query: "..." })` (unchanged) |
| `recall_file({ path_substring: "server.ts" })` | `recall({ path: "server.ts" })` |
| `list_entities({ kind: "project" })` | `recall({})` (no params = entity overview) |
# remember
Source: https://docs.linksee.app/tools/remember
Save, update, or delete memories — unified tool for all write operations
Save, update, or delete memories that persist across sessions and across AI agents. This is the **unified write tool** — it handles create, update, and delete operations based on which parameters you provide.
Memories saved here are accessible from **any** AI agent the user connects to — Claude, GPT, Cursor, Codex, Gemini.
**v0.7.0**: `remember` replaces the previous `remember` + `update_memory` + `forget` tools. Mode is auto-detected from params.
## Modes
### Create (default)
Provide `entity_name` + `entity_kind` + `layer` + `content`:
```json theme={null}
{
"entity_name": "KanseiLink",
"entity_kind": "project",
"layer": "caveat",
"content": "{\"title\":\"freee OAuth Friday deploy\",\"what\":\"Never deploy freee OAuth changes on Friday\",\"why\":\"Their sandbox goes down for maintenance every Friday night JST\"}",
"importance": 0.95
}
```
### Update
Provide `memory_id` + fields to change:
```json theme={null}
{
"memory_id": 42,
"content": "Updated caveat: verified again 2026-05, still applies",
"importance": 0.95
}
```
Preserves `memory_id` and `session_file_edits` links. Preferred over delete + create.
### Delete
Set `forget: true` + `memory_id`:
```json theme={null}
{
"forget": true,
"memory_id": 42
}
```
Caveat-layer and pinned memories (importance >= 0.9) are protected and cannot be deleted.
## Parameters
### Create mode (required)
Name of the entity this memory is about (e.g. "MyProject", "Supabase", "Alice").
One of: `person`, `company`, `project`, `concept`, `file`, `other`.
Memory layer. One of: `goal`, `context`, `emotion`, `implementation`, `caveat`, `learning`.
Common aliases are accepted:
| Alias | Resolves to |
| ------------------------------------ | ---------------- |
| `why`, `intent`, `targets` | `goal` |
| `background`, `reason`, `timing` | `context` |
| `tone`, `feelings`, `mood` | `emotion` |
| `impl`, `how`, `tried` | `implementation` |
| `warning`, `pain`, `pitfall`, `dont` | `caveat` |
| `decision`, `insight`, `growth` | `learning` |
The memory content. Plain text or JSON with structured axes (title, altitude, type, state, what, why, affects, next\_action).
### Optional (all modes)
`0.0` to `1.0`. Set to **0.9 or higher to pin** a memory — pinned memories are protected from auto-forgetting even outside the caveat layer. Default: auto-assigned based on layer.
Optional thread ID to group related memories (e.g. a session ID or decision chain). Enables decision -> implementation -> outcome tracing.
Bypass the paste-back quality check. Set `true` only when you are sure the content is original user or agent thought, not pasted CI logs or assistant output.
### Update mode
The `memory.id` to update. Get this from a prior `recall` response. When provided without `forget: true`, enters update mode.
### Delete mode
Set `true` with a `memory_id` to delete that memory.
## Behavior
1. **Entity resolution**: 3-tier matching — canonical\_key exact -> normalized\_name -> case-insensitive name -> insert new entity
2. **Quality check**: Rejects pasted CI logs, assistant output, and other non-original content (bypass with `force: true`)
3. **Auto-structuring**: Plain text is wrapped into structured JSON with inferred `altitude`, `type`, and `state` classifications
4. **Pinning**: Memories with `importance >= 0.9` get `protected = 1`, preventing auto-forgetting
5. **Events**: Records a `memory_stored` event for momentum tracking
Caveat-layer memories are **always protected** regardless of importance score. They survive consolidation and auto-forgetting indefinitely.
## Migration from pre-v0.7
| Old call | New equivalent |
| -------------------------------------------------- | ----------------------------------------------------------------- |
| `update_memory({ memory_id: 42, content: "..." })` | `remember({ memory_id: 42, content: "..." })` |
| `forget({ memory_id: 42 })` | `remember({ forget: true, memory_id: 42 })` |
| `forget({ dry_run: true })` | No longer exposed — auto-consolidation handles cleanup on startup |