本地语义记忆系统

🧠 Longterm Memory System

A local semantic memory system for LLM applications on macOS

🍎 macOS-only | 🤖 MCP-driven | 🔒 Local embeddings and PostgreSQL storage

🔐 Security

The MCP connection should use the least-privilege ltm_mcp database role. The role can read, add, and update memories but cannot delete, truncate, or change the schema. See SECURITY.md for the security model, verification commands, and the limits of the SQL guards.

🌟 Features

• 🌐 Web Dashboard: Apple-inspired Liquid Glass UI at localhost:5555
• 🕸️ Knowledge Graph: Interactive 2D/3D visualization with D3.js and Three.js
• 🧠 Semantic Search: Local AI-powered embeddings using Ollama + nomic-embed-text (LM Studio fallback)
• 🔌 Browser Extension: Capture web content with context menu and memory badges
• 📦 Archive System: Browse and manage archived memories with full search
• 🤖 MCP Integration: Native Model Context Protocol server for Claude Desktop and other compatible frameworks.
• 🔐 Privacy-First: Embeddings are generated locally without external API calls, and memory data stays in the PostgreSQL instance you configure

📸 Screenshots

Dashboard - Browse View

Light and dark themes with automatic system detection

Timeline & Insights

Visualize memory patterns and discover connections

Semantic Search

Find memories by meaning, not just keywords

Knowledge Graph - 3D View

Interactive visualization with Three.js

Knowledge Graph - 2D View

Force-directed layout with D3.js and focus highlighting

Chrome Extension

Capture web content with the Liquid Glass popup

🖥️ Dashboard

Apple Liquid Glass Design

The dashboard features a modern UI inspired by Apple's design language:

• Solid dark cards with subtle borders and Apple system colors
• Unified navigation across all views (Browse, Timeline, Insights, Archive, Graph)
• Bento grid layouts with 3-column responsive design
• Apple Blue accents (#0A84FF) throughout the interface
• Command palette (⌘K) for keyboard-first navigation

Views

Knowledge Graph

• 3D Mode: Three.js with Fibonacci sphere layout, auto-rotate, orbit controls
• 2D Mode: D3.js force-directed simulation with draggable nodes
• Features: Local view (hop distance), path finding, time animation, node search
• Right-Click Menu: View entity memories in dashboard, start path finding
• Smooth Navigation: Animated camera transitions when focusing nodes
• Color coding: Purple (people), Blue (projects), Green (tech), Orange (websites)

Starting the Dashboard

cd dashboard
python3 app.py
# Opens at http://localhost:5555

🚀 Quick Start

One-Command Installation

curl -fsSL https://raw.githubusercontent.com/MyronKoch/longterm-memory-macos/main/install.sh | bash

The installer prompts for confirmation. For an explicitly confirmed non-interactive install:

curl -fsSL https://raw.githubusercontent.com/MyronKoch/longterm-memory-macos/main/install.sh | LONGTERM_MEMORY_ASSUME_YES=1 bash

What Gets Installed

1. PostgreSQL 17 with pgvector 0.8.0 extension
2. Ollama with nomic-embed-text model (768-dimensional embeddings)
3. Database schema with entities, observations, and archive tables
4. Background services via macOS LaunchAgents
5. Browser extension files (manual Chrome setup required)

Manual Installation

git clone https://github.com/MyronKoch/longterm-memory-macos.git
cd longterm-memory-macos
chmod +x install.sh
./install.sh

🤖 AI Agent Installation

Using Cursor, Windsurf, Claude Code, or another AI coding agent? Just paste this prompt:

Clone https://github.com/MyronKoch/longterm-memory-macos and follow the 
AGENT.md file to install the complete system. Execute each step, verify 
it succeeds, then proceed to the next. Run the health check at the end.

The AGENT.md file contains step-by-step instructions optimized for AI agents with verification checks after each step.

🏗️ Architecture

flowchart TB
    subgraph Inputs[Data Sources]
        Claude[Claude Desktop]
        Browser[Chrome Extension]
    end
    
    subgraph Core[Core System]
        MCP[MCP Server<br/>postgres-mcp]
        NH[Native Host<br/>Python]
        DB[(PostgreSQL 17<br/>+ pgvector)]
        Dash[Dashboard<br/>:5555]
    end
    
    subgraph Services[Background Services]
        Ollama[Ollama<br/>nomic-embed]
        BG[LaunchAgents]
    end
    
    Claude <--> MCP
    MCP <--> DB
    
    Browser <--> NH
    NH <--> DB
    
    Dash <--> DB
    Browser -.->|badge queries| Dash
    
    BG --> DB
    Ollama <--> BG

Multiple machines

This system is single-machine by design right now. To use one memory store from several machines, point every installation at one PostgreSQL instance by setting LONGTERM_MEMORY_HOST and LONGTERM_MEMORY_PORT instead of replicating database dumps.

Backups created by scripts/backup_longterm_memory.sh remain per-machine and are unaffected. A previous whole-database dump-replacement feature was removed because it could silently overwrite newer memories with an older snapshot.

Core Components

🔌 Browser Extension

Capture web content directly from any Chromium browser:

Features

• 🧠 Context Menu: Right-click → "Longterm Memory Database" submenu
  • Save Selection
  • Save Selection + Context
  • Save Entire Page
  • Open Dashboard
• 🔔 Memory Badge: Shows count of memories from current site
• 💡 Auto-Suggestions: Prompts to save frequently visited pages
• ⚙️ Settings: Toggle badge and suggestions on/off

Installation

1. Open chrome://extensions/ and enable Developer Mode
2. Click "Load unpacked" and select browser-extension/chrome-extension/
3. Run ./browser-extension/install_extension.sh for native host setup
4. Copy your extension ID and update the native messaging manifest

📚 See browser-extension/README.md for detailed setup.

🤖 MCP Configuration

Connect to any MCP-compatible AI assistant:

Config Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "longterm-memory": {
      "command": "uvx",
      "args": ["postgres-mcp"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://ltm_mcp@localhost:5432/longterm_memory",
        "SYSTEM_CONTEXT": "PostgreSQL memory for user-specific data. Query at conversation start for context."
      }
    }
  }
}

The server uses the Model Context Protocol. Client setup varies, so consult your client's MCP configuration documentation.

📚 See docs/MULTI_APP_SETUP.md for Claude Code and Cursor configuration.

📖 Usage

Dashboard Commands

# Start dashboard
cd dashboard && python3 app.py

# Access views
open http://localhost:5555              # Browse (default)
open http://localhost:5555/?view=timeline   # Timeline
open http://localhost:5555/?view=insights   # Insights
open http://localhost:5555/?view=archive    # Archive
open http://localhost:5555/graph            # Knowledge Graph

Maintenance

# Health check
./scripts/health_check.sh

# Generate embeddings for new observations
python3 scripts/ollama_embeddings.py

# View logs
tail -f ~/Documents/GitHub/longterm-memory-macos/logs/*.log

⏰ Background Services

The system uses macOS LaunchAgents for scheduled embedding and backup tasks.

Scheduled Jobs

LaunchAgent Files

Located in ~/Library/LaunchAgents/:

Managing Services

# View all longterm-memory services
launchctl list | grep longterm

SQL Queries

-- Recent observations
SELECT * FROM observations ORDER BY created_at DESC LIMIT 10;

-- Semantic search (requires embedding)
SELECT *, embedding <=> '[query_vector]' as distance
FROM observations
WHERE embedding IS NOT NULL
ORDER BY distance LIMIT 10;

-- Query both active and archived
SELECT * FROM all_observations;

-- Entity relationship counts
SELECT e.name, COUNT(o.id) as obs_count
FROM entities e
LEFT JOIN observations o ON e.id = o.entity_id
GROUP BY e.id ORDER BY obs_count DESC;

🎨 Design System

The Liquid Glass design system provides consistent styling across the application:

CSS Files

Key Variables

--brand-primary: #0A84FF;      /* Apple Blue */
--bg-base: #000000;            /* True black background */
--glass-bg: rgba(28, 28, 30, 0.8);  /* Card backgrounds */
--text-primary: rgba(255, 255, 255, 0.95);

🔍 Troubleshooting

Dashboard won't start

# Check Python dependencies
pip3 install flask psycopg2-binary --break-system-packages

# Check PostgreSQL is running
brew services restart postgresql@17

Extension shows connection errors

# Verify native host
python3 browser-extension/native-host/longterm_memory_host.py

# Check extension ID in manifest matches loaded extension

Embeddings not generating

# Verify Ollama is running
ollama list

# Pull the embedding model
ollama pull nomic-embed-text

# If Ollama unavailable, LM Studio fallback is automatic
# Just ensure LM Studio is running with nomic-embed-text-v1.5 loaded

# Manual embedding generation
python3 scripts/ollama_embeddings.py

🗺️ Roadmap

• [ ] Browser extension Liquid Glass redesign
• [ ] Mobile-responsive dashboard
• [ ] Export/import functionality
• [ ] Bulk operations UI
• [ ] Memory clustering visualization
• [ ] Natural language query interface

📄 License

MIT License - see LICENSE for details.

Made in Louisville, KY, with ❤️ for the AI-native workflow

Stack: PostgreSQL 17 • pgvector • Ollama • Flask • Vue 3 • Three.js • D3.js