### Install from Source

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Steps to clone the repository, install dependencies, build the project, and run the server from source code.

```bash
git clone https://github.com/Beledarian/mcp-local-memory.git
cd mcp-local-memory

npm install

npm run build

npm start
```

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

### Configure Global MCP Server

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Configure your MCP settings to use the globally installed local memory server. This example sets the `ARCHIVIST_STRATEGY` environment variable.

```json
{
  "mcpServers": {
    "memory": {
      "command": "mcp-local-memory",
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}
```

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

### Install and Use Global MCP Server

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Install the local memory server globally using npm. This makes the `memory` command available for direct use and configuration.

```bash
npm install -g @beledarian/mcp-local-memory

# Usage
memory --help
```

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

### Configure Local Memory Server

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Example configuration for the mcp-local-memory server using environment variables. Customize paths, strategies, and language settings as needed.

```json
{
  "mcpServers": {
    "local-memory": {
      "command": "wsl",
      "args": ["/home/username/.nvm/versions/node/v20.11.1/bin/node", "/home/username/mcp-local-memory/dist/index.js"],
      "env": {
        "MEMORY_DB_PATH": "/home/username/.memory/memory.db",
        "ARCHIVIST_STRATEGY": "nlp",
        "ARCHIVIST_LANGUAGE": "en"  // Optional: Default is 'en'
      }
    }
  }
}
```

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

### Example Workflow - User Query

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Illustrates the correct workflow for handling user queries by prioritizing internal memory recall before resorting to external searches. Always attempt to recall information internally first.

```text
User: "How do I configure the database?"
❌ DON'T: Immediately search web for generic database config
✅ DO: recall("database configuration") → Use saved approach → If not found, search externally → Save findings
```

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

### Read Resource Example (MCP SDK)

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Demonstrates how to read context snapshots from various memory URIs using the MCP SDK. The output is plain text representing different aspects of the conversation context.

```javascript
const context = await client.readResource({ uri: "memory://current-context" });
// Returns plain text:
// === CURRENT CONTEXT ===
// Active Todos:
// [ ] Review Alice's PR for auth module (ID: td-uuid-...)
//
// Relevant Entities:
// - Alice [Person]
//     • Prefers TypeScript over JavaScript
//     • Uses Neovim as primary editor
// - Project Orion [Project]
//     • React + FastAPI stack
//
// Prominent Relations:
// - Alice --[leads]--> Project Orion
// - Project Orion --[uses]--> PostgreSQL
//
// Recent Memories:
// - Alice prefers TypeScript... (2024-12-01 14:22:00)
```

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

### Configure MCP Local Memory Server via Global Install

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Configure the server as an MCP server entry after a global npm installation. Environment variables can be set to customize archivist strategies and LLM integration.

```json
// Via global npm install
// npm install -g @beledarian/mcp-local-memory
{
  "mcpServers": {
    "memory": {
      "command": "mcp-local-memory",
      "env": {
        "ARCHIVIST_STRATEGY": "nlp,llm",
        "OLLAMA_URL": "http://localhost:11434/api/generate"
      }
    }
  }
}
```

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

### Set Extensions Path for Bundled Tools

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Example command to set the EXTENSIONS_PATH environment variable when using npx. This allows the server to load official or bundled extensions.

```bash
# Example for npx usage
EXTENSIONS_PATH=./node_modules/@beledarian/mcp-local-memory/extensions
```

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

### Initialize a Conversation Session

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Start a new conversation session for complex, multi-step work like project implementations or refactors. This automatically provides startup context.

```python
init_conversation(name="...")
```

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

### Custom Tool Extension Example

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

An example of a custom tool written in TypeScript for the MCP extensions system. This tool queries memories by a content substring using a SQLite database.

```typescript
// ~/.memory/extensions/my_tool.ts
import type { Database } from 'better-sqlite3';

export function handleMyTool(db: Database, args?: { query?: string }) {
    const results = db.prepare(
        "SELECT content FROM memories WHERE content LIKE ? LIMIT 5"
    ).all(`%${args?.query || ''}%`);
    return { matches: results.map((r: any) => r.content) };
}

export const MY_TOOL_TOOL = {
    name: "my_tool",
    description: "Custom memory search by substring",
    inputSchema: {
        type: "object",
        properties: {
            query: { type: "string", description: "Substring to search for" }
        },
        required: ["query"]
    }
};

// MCP config to enable:
// "EXTENSIONS_PATH": "/home/user/.memory/extensions"
```

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

### Initialize Conversation Context

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Call this function at the start of any new technical session to automatically load full startup context, including user information, recent memories, relations, and tasks. This is the mandatory first step for complex work.

```python
init_conversation(name)
```

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

### init_conversation

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Starts a new conversation session, returning a unique conversation ID that scopes subsequent task operations. It's recommended to follow this call with `read_resource("memory://current-context")` to load initial context.

```APIDOC
## init_conversation — Start a Conversation Session

Creates a new conversation record with a UUID and optional name. The returned `conversation_id` scopes subsequent `add_task` calls. Must be followed by `read_resource("memory://current-context")` to load startup context.

### Request Example
```json
{
  "name": "init_conversation",
  "arguments": { "name": "Implementing Orion Auth Module" }
}
```

### Response Example
```json
{
  "conversation_id": "c7f3a1b2-0000-4321-abcd-ef1234567890",
  "name": "Implementing Orion Auth Module",
  "message": "Conversation initialized with ID: c7f3a1b2-.... Content has been offloaded to 'read_resource(\"memory://current-context\")' ..."
}
```
```

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

### list_recent_memories

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Retrieves the most recently inserted memories, ordered by creation date in descending order. This is useful for gaining context at the start of a conversation or session without performing a specific search.

```APIDOC
## list_recent_memories — View Latest Context

Returns the most recently inserted memories ordered by `created_at` descending. Useful for turn-start orientation without a targeted search.

### Request Example
```json
{
  "name": "list_recent_memories",
  "arguments": {
    "limit": 5,
    "json": false
  }
}
```

### Response Example
```
Recent Memories:
 - Alice prefers TypeScript over JavaScript and uses Neovim as her primary editor. [["alice","preferences","tooling"]] (2024-12-01 14:22:00)
 - Project Orion uses a React frontend with a FastAPI backend. [["orion","architecture"]] (2024-12-01 14:21:55)
 ...
```
```

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

### Create a Custom Theme DB Extension

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Define a custom tool for theme-separated memory databases. Ensure your tool logic is encapsulated in a function and export a tool definition object with name, description, and input schema.

```typescript
// my-extensions/my_tool.ts
import type { Database } from 'better-sqlite3';

export function handleMyTool(db: Database, args?: any) {
    // Your tool logic here
    return { result: "Custom tool output" };
}

export const MY_TOOL_TOOL = {
    name: "my_tool",
    description: "Description of what your tool does",
    inputSchema: {
        type: "object",
        properties: {
            // Define input parameters
        }
    }
};
```

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

### Add a Simple Todo

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Create quick, one-off reminders that are not tied to a specific project session. An optional due date can be provided.

```python
add_todo(content, due_date?)
```

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

### Unified CLI Commands

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Utilize the token-efficient CLI for various operations including saving facts, batch operations, searching, graph traversal, task management, todo completion, entity management, and help.

```shell
# Save a fact
{ "name": "cli", "arguments": { "command": "remember \"Alice's favorite framework is React\" --tags alice preferences" } }
```

```shell
# Batch save
{ "name": "cli", "arguments": { "command": "remember \"fact one\" \"fact two\" \"fact three\" --tags batch" } }
```

```shell
# Search
{ "name": "cli", "arguments": { "command": "recall \"project architecture\" --limit 5" } }
```

```shell
# Graph traversal
{ "name": "cli", "arguments": { "command": "graph Alice --depth 2" } }
```

```shell
# Task management
{ "name": "cli", "arguments": { "command": "task add \"Write migration tests\" --section Testing" } }
```

```shell
{ "name": "cli", "arguments": { "command": "task done \"Write migration tests\"" } }
```

```shell
# Todo by name (fuzzy match)
{ "name": "cli", "arguments": { "command": "todo done \"Review Alice's PR\"" } }
```

```shell
# Entity management
{ "name": "cli", "arguments": { "command": "entity create \"Bob\" --type Person --obs \"Backend engineer\" --obs \"Works on CI\"" } }
```

```shell
{ "name": "cli", "arguments": { "command": "relation create \"Bob\" \"Project Orion\" \"maintains\"" } }
```

```shell
# Get help
{ "name": "cli", "arguments": { "command": "help" } }
```

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

### Configure MCP Local Memory Server via npx

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Configure the server as an MCP server entry using npx. Environment variables control various aspects of memory storage, processing, and recall.

```json
// Via npx (recommended – no install required)
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@beledarian/mcp-local-memory"],
      "env": {
        "ARCHIVIST_STRATEGY": "nlp",
        "MEMORY_DB_PATH": "/home/user/.memory/memory.db",
        "CONTEXT_WINDOW_LIMIT": "500",
        "CONTEXT_MAX_ENTITIES": "5",
        "CONTEXT_MAX_MEMORIES": "5",
        "MEMORY_HALF_LIFE_WEEKS": "4",
        "MEMORY_CONSOLIDATION_FACTOR": "1.0",
        "MEMORY_SEMANTIC_WEIGHT": "0.7",
        "TAG_MATCH_BOOST": "0.15",
        "EMBEDDING_CONCURRENCY": "5",
        "USE_WORKER": "true",
        "ENABLE_CONSOLIDATE_TOOL": "false",
        "EXTENSIONS_PATH": "/home/user/.memory/extensions"
      }
    }
  }
}
```

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

### Global Todo System (add_todo, complete_todo, list_todos)

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

A global todo list system where pending todos are accessible in `memory://current-context`. Completing a todo archives it as long-term memory.

```APIDOC
## add_todo / complete_todo / list_todos — Global Todo System

A lightweight global task list. Pending todos automatically appear in `memory://current-context`. Completing a todo archives it as a long-term memory (`"Completed task: ..."`) with tags `["task", "completion"]`.

### Add Todo
#### Request Example
```json
{
  "name": "add_todo",
  "arguments": {
    "content": "Review Alice's PR for auth module",
    "due_date": "2024-12-05"
  }
}
```
#### Response Example
```
"Todo added (ID: td-uuid-...)"
```

### Complete Todo
#### Request Example
```json
{ "name": "complete_todo", "arguments": { "id": "td-uuid-..." } }
```
#### Response Example
```
"Todo completed and saved to memory."
```

### List Todos
#### Request Example
```json
{ "name": "list_todos", "arguments": { "status": "pending", "limit": 10 } }
```
#### Response Example
```markdown
- [ ] Review Alice's PR for auth module (ID: td-uuid-...)
```
```

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

### Read Graph for Overview

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Retrieve a high-level overview of a topic by reading its associated graph in memory. This is recommended as a first step in the search strategy to understand the 'big picture'.

```python
read_graph(center="Topic")
```

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

### cli — Token-Efficient Unified Command Interface

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

A unified command-line interface that accepts shell-style command strings for various operations, reducing token overhead compared to full JSON schemas. It supports subcommands for memory, tasks, todos, entities, and more.

```APIDOC
## cli — Token-Efficient Unified Command Interface

A single tool accepting shell-style command strings, reducing per-call token overhead versus full JSON schemas. Supports all core operations via subcommands.

### Save a Fact
#### Request Example
```json
{ "name": "cli", "arguments": { "command": "remember \"Alice's favorite framework is React\" --tags alice preferences" } }
```

### Batch Save Facts
#### Request Example
```json
{ "name": "cli", "arguments": { "command": "remember \"fact one\" \"fact two\" \"fact three\" --tags batch" } }
```

### Search Facts
#### Request Example
```json
{ "name": "cli", "arguments": { "command": "recall \"project architecture\" --limit 5" } }
```

### Graph Traversal
#### Request Example
```json
{ "name": "cli", "arguments": { "command": "graph Alice --depth 2" } }
```

### Task Management
#### Add Task Example
```json
{ "name": "cli", "arguments": { "command": "task add \"Write migration tests\" --section Testing" } }
```
#### Complete Task Example
```json
{ "name": "cli", "arguments": { "command": "task done \"Write migration tests\"" } }
```

### Todo Management
#### Complete Todo by Name Example
```json
{ "name": "cli", "arguments": { "command": "todo done \"Review Alice's PR\"" } }
```

### Entity Management
#### Create Entity Example
```json
{ "name": "cli", "arguments": { "command": "entity create \"Bob\" --type Person --obs \"Backend engineer\" --obs \"Works on CI\"" } }
```
#### Create Relation Example
```json
{ "name": "cli", "arguments": { "command": "relation create \"Bob\" \"Project Orion\" \"maintains\"" } }
```

### Get Help
#### Request Example
```json
{ "name": "cli", "arguments": { "command": "help" } }
```
```

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

### Configure NPX MCP Server

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Add this configuration to your MCP settings to use the server via NPX. It specifies the command to run and environment variables.

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@beledarian/mcp-local-memory"],
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}
```

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

### consolidate_context

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Retrospective Fact Extraction (Opt-In). Extracts novel structured facts from a brief summary of recent conversation. Enable with `ENABLE_CONSOLIDATE_TOOL=true`. Uses NLP (offline) or LLM (Ollama) strategy. Returns candidate memories for the agent to selectively save.

```APIDOC
## `consolidate_context` — Retrospective Fact Extraction (Opt-In)

Extracts novel structured facts from a brief summary of recent conversation. Enable with `ENABLE_CONSOLIDATE_TOOL=true`. Uses NLP (offline) or LLM (Ollama) strategy. Returns candidate memories for the agent to selectively save.

### Configuration
Enable in MCP config: "ENABLE_CONSOLIDATE_TOOL": "true"

### Request Example
```json
{
  "name": "consolidate_context",
  "arguments": {
    "text": "Discussed deploying Orion to production. Alice is nervous about database migrations. Decided to use Alembic for migrations. Bob will review the CI pipeline next week.",
    "strategy": "nlp",
    "limit": 5
  }
}
```

### Response Example
```
"Extracted 3 novel memories:
 1. Alice is nervous about database migrations. (importance: 0.6, tags: alice, orion, deployment)
 2. Orion will use Alembic for database migrations. (importance: 0.7, tags: orion, alembic, migrations)
 3. Bob will review the CI pipeline next week. (importance: 0.5, tags: bob, orion, ci)

 To save a memory: remember_fact(text="...", tags=[...])"
```
```

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

### Export Extensions Path

Source: https://github.com/beledarian/mcp-local-memory/blob/main/extensions/README.md

Set the EXTENSIONS_PATH environment variable to the directory containing the extensions. The server will automatically load .ts or .js files from this path.

```bash
export EXTENSIONS_PATH=$(pwd)/extensions
```

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

### Initialize Conversation Session

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Creates a new conversation session. The returned `conversation_id` is required for subsequent conversation-scoped operations. Ensure `read_resource("memory://current-context")` is called afterward to load initial context.

```json
{
  "name": "init_conversation",
  "arguments": { "name": "Implementing Orion Auth Module" }
}
```

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

### Complete a Todo

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Mark a todo as complete. This action automatically archives the task to memory.

```python
complete_todo(id)
```

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

### Recall Information from Memory

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Use `recall()` to query memory for specific information before making assumptions. This ensures accuracy by retrieving user-specific data.

```python
recall("global agent rules location")
```

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

### Global Todo System Operations

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Manage a global list of todos. Pending todos are visible in `memory://current-context`. Completing a todo archives it as long-term memory with specific tags.

```json
// Create a todo with optional due date
{
  "name": "add_todo",
  "arguments": {
    "content": "Review Alice's PR for auth module",
    "due_date": "2024-12-05"
  }
}
```

```json
// Complete it (also writes a memory)
{ "name": "complete_todo", "arguments": { "id": "td-uuid-..." } }
```

```json
// List pending
{ "name": "list_todos", "arguments": { "status": "pending", "limit": 10 } }
```

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

### Memory Decay and Consolidation Formula

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Explains the SQL function `ranked_score` used for recall ranking, detailing the factors influencing memory stability and decay. Includes default tuning parameters and importance growth from recall.

```plaintext
Stability   = halfLife × (1 + consolidationFactor × log₂(access_count + 1))
DecayedImp  = importance × 0.5^(weeks_since_access / stability)
Similarity  = 1.0 - cosine_distance
FinalScore  = (similarity × semanticWeight) + (decayedImportance × importanceWeight)

Default tuning:
  halfLife            = 4 weeks    (MEMORY_HALF_LIFE_WEEKS)
  consolidationFactor = 1.0        (MEMORY_CONSOLIDATION_FACTOR)
  semanticWeight      = 0.7        (MEMORY_SEMANTIC_WEIGHT)
  tagBoost            = +0.15      (TAG_MATCH_BOOST, applied post-query for exact tag matches)

Importance growth from recall:
  importance = 0.5 + 0.5 × (ln(access_count + 1) / ln(21))
  → ~10 recalls → importance ~0.7 ("cherished")
  → ~20 recalls → importance ~1.0 (maximum)
```

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

### Consolidate Context with LLM Strategy

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Extracts important facts from a conversation summary using the LLM strategy. Requires Ollama and is more thorough but costly in tokens. Enable via ENABLE_CONSOLIDATE_TOOL=true.

```javascript
consolidate_context(text="Discussed Python for data science, TypeScript frustrations, CEOSim project", strategy="llm")
```

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

### Backup All Memories with `export_memories`

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Dumps the complete `memories` table to a JSON file at the specified absolute path using `fs-extra`. The output file structure is an array of memory rows.

```json
{
  "name": "export_memories",
  "arguments": {
    "path": "/home/user/backups/memory-2024-12-01.json"
  }
}
```

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

### Cluster Memories with cluster_memories

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Groups memories and entities into a specified number of semantic clusters using a 'gravity center' algorithm. Useful for high-level knowledge organization.

```json
{
  "name": "cluster_memories",
  "arguments": { "k": 4 }
}
```

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

### Recall Information from Memory

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Use this function to search for information within the internal memory. It's crucial to use this before consulting external sources. For temporal queries, use specific phrasing like 'what did we do yesterday?'.

```python
recall(query)
```

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

### Consolidate Context with consolidate_context

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Extracts novel structured facts from a text summary using NLP or an LLM strategy. Requires `ENABLE_CONSOLIDATE_TOOL=true` to be set. Returns candidate memories for agent review.

```json
// Enable in MCP config: "ENABLE_CONSOLIDATE_TOOL": "true"

{
  "name": "consolidate_context",
  "arguments": {
    "text": "Discussed deploying Orion to production. Alice is nervous about database migrations. Decided to use Alembic for migrations. Bob will review the CI pipeline next week.",
    "strategy": "nlp",
    "limit": 5
  }
}
```

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

### List Latest Memories with `list_recent_memories`

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Retrieves the most recently inserted memories ordered by `created_at` descending. Useful for turn-start orientation without a targeted search. Set `json` to `true` for JSON output.

```json
{
  "name": "list_recent_memories",
  "arguments": {
    "limit": 5,
    "json": false
  }
}
```

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

### Recall Memories by Project Tag

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Searches for memories tagged with a specific project name. This prioritizes memories associated with projects like 'Project Alpha'.

```javascript
recall("Project Alpha")
```

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

### Run Auto-Ingestion NLP Tests

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Tests the automatic ingestion of data using NLP techniques.

```typescript
npx tsx test_archivist_nlp.ts
```

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

### Read and Explore the Knowledge Graph

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Explore linked facts within the knowledge graph. You can specify a center entity and depth for focused exploration.

```python
read_graph(center?, depth?)
```

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

### Run Core Verification Tests

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Executes the internal verification tests for the core functionality of the system.

```typescript
npx tsx test_verification.ts
```

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

### read_graph

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Explore the Knowledge Graph. Returns entities, relations, related memories, and a Mermaid diagram for a specified entity center or a global overview. Supports multi-hop traversal up to depth 3.

```APIDOC
## `read_graph` — Explore the Knowledge Graph

Returns entities, relations, related memories, and a Mermaid diagram for a specified entity center (or a global overview if no center is given). Supports multi-hop traversal up to depth 3 ("friends of friends").

### Request Example (Focused view on one entity)
```json
{
  "name": "read_graph",
  "arguments": {
    "center": "Alice",
    "depth": 2
  }
}
```

### Response Example (Human-readable with Mermaid):
```
Knowledge Graph for "Alice":
---
Relations
---
- Alice --(leads)--> Project Orion
- Alice --(prefers)--> TypeScript
- Alice --(uses)--> Neovim
- Project Orion --(uses)--> PostgreSQL

```mermaid
graph TD
  Alice["Alice (Person)"]
  Project_Orion["Project Orion (Project)"]
  Alice -->|leads| Project_Orion
  ...
```

---
Key Entities
---
- Alice (Person) ⭐
- Project Orion (Project)

---
Top Related Memories
---
- Alice prefers TypeScript over JavaScript and uses Neovim as her primary editor. [alice, preferences]
```

### Request Example (JSON output for programmatic use)
```json
{
  "name": "read_graph",
  "arguments": { "center": "Alice", "depth": 1, "json": true }
}
```

### Response Example (JSON output):
```json
{ "nodes": [...], "edges": [...], "relatedMemories": [...] }
```
```

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

### Create or Update an Entity

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Define or update an entity in the knowledge graph. The 'Smart Append' feature adds new observations to existing entities.

```python
create_entity(name, type, observations?)
```

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

### Run Graph Database Tests

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Verifies the integrity and functionality of the graph database layer.

```typescript
npx tsx test_graph.ts
```

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

### Cluster Memories

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Group existing knowledge into thematic clusters using `cluster_memories`. An optional parameter `k` can specify the number of clusters.

```python
cluster_memories(k?)
```

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

### Create a Relation Between Entities

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Link two entities in the knowledge graph by specifying the source, target, and the nature of the relation.

```python
create_relation(source, target, relation)
```

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

### Perform Semantic and Keyword Search with `recall`

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Use `recall` for semantic search, falling back to FTS5 if vector search is unavailable. Supports natural-language date filters parsed by `chrono-node`. Results are ranked by a weighted score combining semantic similarity and decayed importance.

```json
{
  "name": "recall",
  "arguments": {
    "query": "What editor does Alice use?",
    "limit": 3
  }
}
```

```json
{
  "name": "recall",
  "arguments": {
    "query": "project decisions last week",
    "limit": 5,
    "debug": true
  }
}
```

```json
{
  "name": "recall",
  "arguments": {
    "query": "deployment issues",
    "startDate": "2024-11-01T00:00:00Z",
    "endDate": "2024-11-30T23:59:59Z",
    "limit": 10,
    "json": true
  }
}
```

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

### cluster_memories

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Topic-Based Memory Clustering. Groups memories and entities into k semantic clusters using a "gravity center" algorithm. Useful for high-level understanding of stored knowledge.

```APIDOC
## `cluster_memories` — Topic-Based Memory Clustering

Groups memories and entities into k semantic clusters using a "gravity center" algorithm. Useful for high-level understanding of stored knowledge.

### Request Example
```json
{
  "name": "cluster_memories",
  "arguments": { "k": 4 }
}
```

### Response Example (JSON):
```json
{
  "clusters": [
    {
      "id": 0,
      "label": "Project Orion Development",
      "members": [
        { "type": "memory", "content": "Project Orion uses a React frontend..." },
        { "type": "entity", "name": "Project Orion" },
        { "type": "memory", "content": "The Orion database is PostgreSQL 15..." }
      ]
    },
    {
      "id": 1,
      "label": "Alice Personal Preferences",
      "members": [...] 
    }
  ]
}
```
```

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

### Link Entities with `create_relation`

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Creates a directed edge `source --[relation]--> target` in the relations table. If an entity does not exist, it is auto-created with type `"Unknown"`.

```json
{
  "name": "create_relation",
  "arguments": {
    "source": "Alice",
    "target": "Project Orion",
    "relation": "leads"
  }
}
```

```json
{
  "name": "create_relation",
  "arguments": {
    "source": "Project Orion",
    "target": "PostgreSQL",
    "relation": "uses"
  }
}
```

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

### Remember Facts

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Save new information into memory using `remember_fact` or `remember_facts`. Automatic entity extraction is enabled.

```python
remember_fact/facts
```

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

### Create or Enrich Knowledge Graph Entity with `create_entity`

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Creates a new entity or appends observations to an existing one using Levenshtein fuzzy matching. A 384-dim embedding is generated for new entities in the background.

```json
{
  "name": "create_entity",
  "arguments": {
    "name": "Project Orion",
    "type": "Project",
    "observations": [
      "React + FastAPI stack",
      "PostgreSQL 15 database",
      "Led by Alice"
    ]
  }
}
```

```json
{
  "name": "create_entity",
  "arguments": {
    "name": "Project Orion",
    "type": "Project",
    "observations": ["Deployment target: Ubuntu 22.04 bare-metal"]
  }
}
```

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

### create_entity

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Adds a new entity (like a person, project, or technology) to the knowledge graph or enriches an existing one with new observations. It handles duplicate detection using fuzzy matching and generates embeddings in the background.

```APIDOC
## create_entity — Add or Enrich a Knowledge Graph Node

Creates a new entity (person, project, technology, etc.) in the graph with optional observations. Uses Levenshtein fuzzy matching (distance ≤ 2) to detect duplicates; if a match exists, new observations are appended ("Smart Append"). A 384-dim embedding is generated for the entity in the background.

### Parameters
#### Arguments
- **name** (string) - Required - The name of the entity.
- **type** (string) - Required - The type of the entity (e.g., "Project", "Person").
- **observations** (array of strings) - Optional - A list of observations or details about the entity.

### Request Example (Create New Entity)
```json
{
  "name": "create_entity",
  "arguments": {
    "name": "Project Orion",
    "type": "Project",
    "observations": [
      "React + FastAPI stack",
      "PostgreSQL 15 database",
      "Led by Alice"
    ]
  }
}
```

### Request Example (Smart Append - Entity Exists)
```json
{
  "name": "create_entity",
  "arguments": {
    "name": "Project Orion",
    "type": "Project",
    "observations": ["Deployment target: Ubuntu 22.04 bare-metal"]
  }
}
```

### Response Example (Create)
```
Created entity 'Project Orion' of type 'Project'.
```

### Response Example (Smart Append)
```
Entity 'Project Orion' already exists (as 'Project Orion'). Appended 1 new observations.
```
```

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

### export_memories

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Exports all memories from the `memories` table into a JSON file at a specified absolute path. This function is useful for backing up the entire memory store.

```APIDOC
## export_memories — Backup All Memories to JSON

Dumps the complete `memories` table to a JSON file at the given absolute path using `fs-extra`.

### Parameters
#### Arguments
- **path** (string) - Required - The absolute path where the JSON backup file will be saved.

### Request Example
```json
{
  "name": "export_memories",
  "arguments": {
    "path": "/home/user/backups/memory-2024-12-01.json"
  }
}
```

### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "Successfully exported 142 memories to /home/user/backups/memory-2024-12-01.json"
    }
  ]
}
```

### Output File Structure Example
```json
[
  {
    "id": "...",
    "content": "...",
    "created_at": "...",
    "tags": "[\"alice\"]",
    "importance": 0.72,
    "access_count": 14
  },
  ...
]
```
```

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

### Cluster Memories for Thematic Overview

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Obtain a bird's-eye view of memory content by clustering memories into thematic groups. This function helps in understanding the main topics present in the memory.

```python
cluster_memories(k=5)
```

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

### create_relation

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Establishes a directed relationship between two entities in the knowledge graph. If either the source or target entity does not exist, it will be automatically created with the type 'Unknown'.

```APIDOC
## create_relation — Link Two Entities

Creates a directed edge `source --[relation]--> target` in the relations table. If either entity doesn't exist yet, it is auto-created with type "Unknown".

### Parameters
#### Arguments
- **source** (string) - Required - The name of the source entity.
- **target** (string) - Required - The name of the target entity.
- **relation** (string) - Required - The type of relationship between source and target.

### Request Example 1
```json
{
  "name": "create_relation",
  "arguments": {
    "source": "Alice",
    "target": "Project Orion",
    "relation": "leads"
  }
}
```

### Response Example 1
```
Created relation: Alice --[leads]--> Project Orion
```

### Request Example 2
```json
{
  "name": "create_relation",
  "arguments": {
    "source": "Project Orion",
    "target": "PostgreSQL",
    "relation": "uses"
  }
}
```

### Response Example 2
```
Created relation: Project Orion --[uses]--> PostgreSQL
```
```

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

### Run AI Model Embedding Tests

Source: https://github.com/beledarian/mcp-local-memory/blob/main/README.md

Checks the AI model's embedding generation and accuracy.

```typescript
npx tsx test_embedding.ts
```

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

### MCP Tool Call: remember_facts

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Use the `remember_facts` tool for batch saving multiple facts. This method is significantly faster for large datasets as it processes embeddings and archivist tasks in parallel batches.

```json
{
  "name": "remember_facts",
  "arguments": {
    "facts": [
      { "text": "Project Orion uses a React frontend with a FastAPI backend.", "tags": ["orion", "architecture"] },
      { "text": "The Orion database is PostgreSQL 15 hosted on a local VM.", "tags": ["orion", "database"] },
      { "text": "Alice is the lead developer of Project Orion.", "tags": ["orion", "alice", "team"] },
      { "text": "Deployment target for Orion is a bare-metal Ubuntu 22.04 server.", "tags": ["orion", "deployment"] }
    ]
  }
}
```

```json
// Response
{
  "content": [{ "type": "text", "text": "Queued 4 facts for memory." }]
}
```

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

### recall

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Performs a semantic and keyword search on memories. It supports natural-language date filters and falls back to FTS5 if vector indexing is unavailable. Results are ranked by a weighted score combining semantic similarity and decayed importance.

```APIDOC
## recall — Semantic + Keyword Search

Searches memories using vector cosine similarity (with temporal-decay scoring), falling back to FTS5 if the vector index is unavailable. Supports natural-language date filters ("Time Tunnel") parsed by `chrono-node`. Results are ranked by a weighted score combining semantic similarity and decayed importance; exact tag matches receive a configurable boost.

### Request Example (Basic Semantic Search)
```json
{
  "name": "recall",
  "arguments": {
    "query": "What editor does Alice use?",
    "limit": 3
  }
}
```

### Request Example (Time Tunnel - Natural Language Dates)
```json
{
  "name": "recall",
  "arguments": {
    "query": "project decisions last week",
    "limit": 5,
    "debug": true
  }
}
```

### Request Example (Explicit Date Range + JSON Output)
```json
{
  "name": "recall",
  "arguments": {
    "query": "deployment issues",
    "startDate": "2024-11-01T00:00:00Z",
    "endDate": "2024-11-30T23:59:59Z",
    "limit": 10,
    "json": true
  }
}
```

### Response Example (Default Human-Readable)
```
Found 2 relevant memories via vector:
 1. Alice prefers TypeScript over JavaScript and uses Neovim as her primary editor. (Score: 0.91) [Imp: 0.55] Tags: ["alice","preferences","tooling"]
 2. Alice uses tmux alongside Neovim for terminal multiplexing. (Score: 0.74) [Imp: 0.50]
```

### Response Example (JSON Output)
```json
{
  "results": [
    {
      "id": "...",
      "content": "...",
      "score": 0.88,
      "importance": 0.72,
      ...
    }
  ]
}
```
```

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

### Add a Task to a Conversation

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Organize work within a conversation by adding tasks. Tasks can be categorized by section for better management.

```python
add_task(content, section, conversation_id)
```

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

### Delete a Task

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Mandatory cleanup step: remove completed or obsolete tasks using `delete_task()` to prevent context pollution.

```python
delete_task(id)
```

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

### Conversation-Scoped Tasks (add_task, update_task_status, list_tasks, delete_task)

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Manage tasks within a conversation or globally. Tasks can be added, their status updated (pending, in-progress, complete), listed, or deleted. It's advised to remove completed tasks to maintain context cleanliness.

```APIDOC
## add_task / update_task_status / list_tasks / delete_task — Conversation-Scoped Tasks

Tasks can be scoped to a conversation or global (no `conversation_id`). Status values: `pending`, `in-progress`, `complete`. Always delete completed/obsolete tasks to prevent context pollution.

### Add Task
#### Request Example
```json
{
  "name": "add_task",
  "arguments": {
    "content": "Implement JWT middleware",
    "section": "Backend",
    "conversation_id": "c7f3a1b2-0000-4321-abcd-ef1234567890"
  }
}
```
#### Response Example
```json
{ "task_id": "t1a2b3c4-...", "message": "Task added with ID: t1a2b3c4-..." }
```

### Update Task Status
#### Request Example
```json
{
  "name": "update_task_status",
  "arguments": { "id": "t1a2b3c4-...", "status": "in-progress" }
}
```

### List Tasks for a Conversation
#### Request Example
```json
{
  "name": "list_tasks",
  "arguments": { "conversation_id": "c7f3a1b2-0000-4321-abcd-ef1234567890" }
}
```
#### Response Example
Returns markdown checklist:
```markdown
## Backend
- [/] Implement JWT middleware (ID: t1a2b3c4-...)
- [ ] Write unit tests for auth (ID: t5d6e7f8-...)
```

### List All Tasks
#### Request Example
```json
{ "name": "list_tasks", "arguments": { "conversation_id": "__all__" } }
```

### Delete Task
#### Request Example
```json
{ "name": "delete_task", "arguments": { "id": "t1a2b3c4-..." } }
```
```

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

### Manage Conversation Tasks

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Add, update status, list, or delete tasks within a specific conversation. Tasks can also be listed globally. Remember to delete completed tasks to maintain context efficiency.

```json
// Add tasks to a conversation
{
  "name": "add_task",
  "arguments": {
    "content": "Implement JWT middleware",
    "section": "Backend",
    "conversation_id": "c7f3a1b2-0000-4321-abcd-ef1234567890"
  }
}
```

```json
// Mark in-progress
{
  "name": "update_task_status",
  "arguments": { "id": "t1a2b3c4-...", "status": "in-progress" }
}
```

```json
// List tasks for a conversation
{
  "name": "list_tasks",
  "arguments": { "conversation_id": "c7f3a1b2-0000-4321-abcd-ef1234567890" }
}
```

```json
// Show all tasks across all conversations
{ "name": "list_tasks", "arguments": { "conversation_id": "__all__" } }
```

```json
// Delete a completed task
{ "name": "delete_task", "arguments": { "id": "t1a2b3c4-..." } }
```

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

### Save Multiple Facts to Memory

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Use this plural function to save multiple distinct pieces of information to memory simultaneously. This is more efficient for batching items like lists of preferences or specialized knowledge, reducing latency.

```python
remember_facts()
```

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

### MCP Tool Call: remember_fact

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Use the `remember_fact` tool to save a single memory record. The server processes embeddings and entity extraction asynchronously. This tool is useful for immediate storage of discrete pieces of information.

```json
// MCP tool call
{
  "name": "remember_fact",
  "arguments": {
    "text": "Alice prefers TypeScript over JavaScript and uses Neovim as her primary editor.",
    "tags": ["alice", "preferences", "tooling"]
  }
}
```

```json
// Response
{
  "content": [{ "type": "text", "text": "Remembered fact with ID: a3f1c2d4-88b0-4e2a-9f3b-000111222333" }]
}
```

```json
// With nlp/llm archivist enabled, the server automatically extracts:
//   Entity: "Alice" (Person)
//   Entity: "TypeScript" (Technology)
//   Entity: "Neovim" (Tool)
//   Relation: Alice --[prefers]--> TypeScript
//   Relation: Alice --[uses]--> Neovim
```

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

### Save a Single Fact to Memory

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Use this function to save a single piece of important information to memory. It's recommended to call this frequently whenever the user shares critical details, project information, technical decisions, or useful solutions.

```python
remember_fact()
```

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

### Read Graph Data with read_graph

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Retrieves entities, relations, and related memories for a given entity or a global overview. Supports multi-hop traversal up to depth 3. Use `json: true` for programmatic access.

```json
{
  "name": "read_graph",
  "arguments": {
    "center": "Alice",
    "depth": 2
  }
}
```

```json
{
  "name": "read_graph",
  "arguments": { "center": "Alice", "depth": 1, "json": true }
}
```

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

### Update Task Status

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/example_prompt.md

Track the progress of tasks by updating their status to 'pending', 'in-progress', or 'complete'.

```python
update_task_status(id, status)
```

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

### remember_facts

Source: https://context7.com/beledarian/mcp-local-memory/llms.txt

Batches multiple facts for saving. This operation is transactional and processes embeddings and archivist tasks in parallel batches, offering significant speed improvements for large datasets.

```APIDOC
## remember_facts

### Description
Saves all facts transactionally in a single pass, then processes embeddings and archivist in parallel batches (controlled by `EMBEDDING_CONCURRENCY`). Roughly 7× faster than sequential single calls for large batches.

### Method
MCP Tool Call

### Parameters
#### Arguments
- **facts** (array of objects) - Required - An array of fact objects, where each object contains 'text' and optional 'tags'.
  - **text** (string) - Required - The fact to be remembered.
  - **tags** (array of strings) - Optional - Tags associated with the fact.

### Request Example
```json
{
  "name": "remember_facts",
  "arguments": {
    "facts": [
      { "text": "Project Orion uses a React frontend with a FastAPI backend.", "tags": ["orion", "architecture"] },
      { "text": "The Orion database is PostgreSQL 15 hosted on a local VM.", "tags": ["orion", "database"] },
      { "text": "Alice is the lead developer of Project Orion.", "tags": ["orion", "alice", "team"] },
      { "text": "Deployment target for Orion is a bare-metal Ubuntu 22.04 server.", "tags": ["orion", "deployment"] }
    ]
  }
}
```

### Response
#### Success Response
- **content** (array) - Contains a text object indicating the number of facts queued.

### Response Example
```json
{
  "content": [{ "type": "text", "text": "Queued 4 facts for memory." }]
}
```
```

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

### Updating Entities with update_entity()

Source: https://github.com/beledarian/mcp-local-memory/blob/main/docs/detailed_prompt.md

Modify an existing entity by renaming it or changing its type. Provide the current name and the new name or type.

```python
update_entity(current_name, new_name?, new_type?)
```