Documentation — MNESIQ

MNESIQ

Documentation

Persistent AI memory, stored on your machine

Getting Started Connect Claude.ai Tools Reference (11 tools) Access Control Troubleshooting

Getting Started

1. Install MNESIQ

npm install -g mnesiq
mnesiq

This starts the MNESIQ server at http://localhost:4200. Open it in your browser. The setup wizard will detect your hardware and recommend a model, or you can add a cloud API key.

2. Connect to the Relay

The relay makes your MNESIQ reachable from the internet so Claude.ai and other cloud LLMs can connect.

Open MNESIQ at localhost:4200
Click Gateway in the top bar
Go to the Relay tab
Sign up with your email
You'll get a public endpoint like yourname.mcp.amnesiaiq.ai

The relay is zero-knowledge. It routes encrypted WireGuard traffic without seeing, storing, or logging your memory data.

Connect Claude.ai

From the Connector Directory

In Claude.ai, go to Settings → Connectors
Find MNESIQ and click Add
Authorize on the consent page with your relay account
Done — Claude now has 11 memory tools

Custom Connector

In Claude.ai, go to Settings → Connectors → Add Custom
Enter URL: https://api.amnesiaiq.ai/mcp
Leave Client ID and Secret blank (auto-registered via OAuth)
Authorize with your relay account

What Claude Can Do

Once connected, Claude automatically:

Loads your memory passport at the start of each conversation
Remembers facts, preferences, goals, and decisions you share
Recalls relevant context from past conversations
Tracks your goals and proactively surfaces relevant information
Manages named lists (todo, reading, shopping, etc.)

Tools Reference

Read Tools

recall_context read

Search memories by natural language query. Returns the most relevant matches with confidence scores.

Parameters: query (required), domain, category, max_results

get_passport read

Generate a signed context bundle of your most relevant memories for system prompt injection.

Parameters: domain, max_tokens

get_full_context read

Passport + proactive items combined. The recommended session-start call.

Parameters: topic, domain

get_proactive_context read

High-priority context: active goals, risk rules, approaching deadlines.

Parameters: conversation_summary (required), domain

analyze_for_extraction read

Analyze conversation text for extractable facts before storing. Preview without committing.

Parameters: text (required)

Write Tools

remember_context write

Store a memory. Categories: fact, preference, goal, skill, behavior_pattern, relationship, opinion, list_item.

Parameters: content (required), category, domain, confidence, clearance

extract_from_conversation write

Batch-extract and store multiple memories from a conversation segment.

Parameters: memories (required, array), domain

set_intent write

Create a goal with lifecycle tracking: stated → active → fulfilled / deferred / abandoned.

Parameters: content (required), domain, target_date, fulfillment_criteria

update_intent_status write

Transition a goal through its lifecycle.

Parameters: intent_id (required), status (required), evidence

manage_list write

Add, complete, or dismiss items from named lists (todo, reading, watch, shopping, etc.).

Parameters: list_name (required), action (required), content, item_id

consolidate_context destructive

Compress old granular memories into higher-order insights. Source memories are archived.

Parameters: domain, category

Access Control

Clearance Levels

Each connected LLM is assigned a clearance level. Higher clearance sees everything below it.

Top Secret — full access including vault items
Secret — sensitive data (PII, financial, relationships)
Confidential — standard access (preferences, goals, skills)
Unclassified — public facts only

Compartments

Compartments restrict topic access. A client assigned to "work" only sees memories from clients that share the "work" compartment. Use "all" for unrestricted access.

Memories inherit the clearance of the client that stored them. The LLM never knows its clearance level — all gating happens server-side. Configure access in the MNESIQ Gateway → Clients tab.

Troubleshooting

Claude says "Authorization failed"

Remove the MNESIQ connector in Claude.ai and re-add it
Check that your relay is connected (green dot in MNESIQ topbar)
Verify your relay account credentials

Tools return errors

Check that MNESIQ is running at localhost:4200
Check relay status: green dot in topbar = connected
Open Gateway → Memory to verify the memory engine is working

Memories not appearing

Click the refresh button in Gateway → Memory → Browse
Check clearance levels — the recalling client may not have access
Check compartments — both clients must share a compartment

Relay won't connect

Check your internet connection
Verify your relay account in Gateway → Relay
Check https://api.amnesiaiq.ai/health to verify the relay is up

Slow first response

The first memory operation may take a few seconds while the embedding model loads. Subsequent operations are fast. With Ollama running locally, embeddings are nearly instant.