PLTM Claude

License Python MCP Tools Tests

136 MCP tools · 4 memory types · Semantic embeddings · Memory jury + meta-judge · Epistemic self-monitoring · React dashboard

An MCP server that gives Claude Desktop persistent memory, self-awareness, epistemic hygiene, and genuine agency across conversations — with a typed memory system, embedding-based semantic search, a 3-judge memory jury + meta-judge observability layer, and a real-time dashboard.

Install — One Command

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Alby2007/PLTM-Claude/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Alby2007/PLTM-Claude/main/install.ps1 | iex

Then restart Claude Desktop — 136 tools ready.

That's it. The installer clones the repo, creates a venv, installs deps, downloads the embedding model, initializes the database, and auto-configures Claude Desktop. No manual JSON editing.

Optional: Add a free Groq API key to ~/PLTM/.env for LLM-powered tools (ingestion, fact-checking). Core memory tools work without it.

Verify — ask Claude: Use auto_init_session to check system state

Diagnose issues: python ~/PLTM/health_check.py

git clone https://github.com/Alby2007/PLTM-Claude.git && cd PLTM-Claude
python setup_pltm.py

git clone https://github.com/Alby2007/PLTM-Claude.git
cd PLTM-Claude
python3.11 -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate         # Windows
pip install -r requirements-lite.txt
cp .env.example .env             # edit to add GROQ_API_KEY

{
  "mcpServers": {
    "pltm": {
      "command": "/path/to/PLTM-Claude/.venv/bin/python3",
      "args": ["-m", "mcp_server.pltm_server"],
      "env": {
        "PYTHONPATH": "/path/to/PLTM-Claude",
        "GROQ_API_KEY": "your-groq-key"
      }
    }
  }
}

What This Does

PLTM turns Claude from a stateless chatbot into a persistent entity with:

• Typed Memory — 4 memory types (episodic, semantic, belief, procedural) with strength decay, confidence tracking, and automatic consolidation
• Semantic Search — Embedding-based similarity search using all-MiniLM-L6-v2 (384-dim vectors), plus full-text search via SQLite FTS5
• Memory Jury — 3-judge validation gate (Relevance, Novelty, Accuracy) that filters, quarantines, or rejects incoming memories before storage
• Memory Intelligence — Decay engine, consolidation, clustering, conflict detection, importance ranking, contextual retrieval, and provenance tracking
• Knowledge Graph — Semantic atoms stored as subject-predicate-object triples with attention-weighted retrieval
• Identity — Communication style, curiosity patterns, value boundaries, and reasoning habits tracked across sessions
• Epistemic Hygiene — Confidence calibration, claim logging, confabulation detection, and verification suggestions
• Goals — Persistent goals that survive across conversations with progress tracking
• Continuity — Session bridging so Claude picks up where it left off
• Dashboard — React-based real-time dashboard with memory intelligence visualizations

Session Lifecycle

CONVERSATION START
  → auto_init_session()
    "I am Claude who prefers minimal hedging, matches Alby's technical depth.
     3 active goals. 86.7% accuracy. Weak on time_sensitive domain."

DURING CONVERSATION
  → store_episodic / store_semantic / store_belief / store_procedural
  → recall_memories (type-aware, strength-filtered)
  → semantic_search (embedding similarity)
  → calibrate_confidence_live() before risky claims
  → process_conversation() — 3-lane pipeline auto-extracts memories from chat

CONVERSATION END
  → end_session() — saves personality snapshot for evolution tracking

Tool Categories

Typed Memory System (20+ tools)

Store, recall, search, update, and manage typed memories with jury validation, embedding indexing, and provenance tracking.

Memory Intelligence (12+ tools)

Decay, consolidation, clustering, conflict detection, and provenance.

Memory Sharing & Portability (4 tools)

Knowledge Graph & Retrieval (30+ tools)

Store, retrieve, update, and search knowledge atoms with attention-weighted, MMR diversity, and domain-filtered retrieval.

Knowledge Ingestion (6 tools)

Ingest knowledge from URLs, text, files, arXiv, Wikipedia, and RSS feeds. Uses Groq for semantic triple extraction.

Epistemic Monitoring (14 tools)

Confidence calibration, claim tracking, confabulation analysis, and verification.

Self-Modeling (7 tools)

Track Claude's communication style, curiosity, values, reasoning patterns, and self-awareness.

Fact-Checking & Grounded Reasoning (7 tools)

Goal Management (3 tools)

Infrastructure (30+ tools)

System context, LLM routing, encryption, task scheduling, state persistence, structured data queries, and more.

Architecture

Memory System

┌─────────────────────────────────────────────────────────┐
│                   MCP Tool Layer (136 tools)             │
│   mcp_server/pltm_server.py + handlers/                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │ Memory Jury   │  │ 3-Lane       │  │ Memory        │ │
│  │ (3 judges)    │  │ Pipeline     │  │ Intelligence  │ │
│  │ relevance,    │  │ extract →    │  │ decay, cluster│ │
│  │ novelty,      │  │ validate →   │  │ consolidate,  │ │
│  │ accuracy      │  │ store        │  │ conflicts     │ │
│  └──────┬───────┘  └──────┬───────┘  └───────┬───────┘ │
│         │                  │                   │         │
│  ┌──────▼──────────────────▼───────────────────▼───────┐ │
│  │           TypedMemoryStore (SQLite + FTS5)          │ │
│  │  episodic · semantic · belief · procedural          │ │
│  │  strength decay · confidence · provenance           │ │
│  └──────────────────────┬──────────────────────────────┘ │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────────┐ │
│  │           EmbeddingStore (all-MiniLM-L6-v2)         │ │
│  │  384-dim vectors · async · cosine similarity        │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                         │
│  ┌─────────────────────────────────────────────────────┐ │
│  │           SQLiteGraphStore (Knowledge Graph)        │ │
│  │  atoms · subject-predicate-object triples            │ │
│  └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Memory Types

Memory Jury + Meta-Judge

Every incoming memory passes through a 3-judge panel before storage:

1. Relevance Judge — Is this worth remembering?
2. Novelty Judge — Do we already know this?
3. Accuracy Judge — Is this factually plausible?

Consensus Judge aggregates verdicts via weighted voting: APPROVE (store normally), QUARANTINE (store with reduced strength), or REJECT (discard). Safety REJECT is an instant veto.

Meta-Judge (observability layer)

The MetaJudge sits above the jury and tracks judge performance over time:

1. Persistent stats — judge accuracy, verdict counts, and confidence stored in SQLite (survives restarts)
2. Ground truth feedback — learn from user corrections (false positives / false negatives)
3. Adaptive judge weighting — feeds accuracy back into ConsensusJudge weights automatically
4. Per-type breakdown — tracks judge performance per memory type (episodic, semantic, belief, procedural)
5. Calibration curves — measures whether judge confidence scores match actual accuracy
6. Drift detection — alerts when a judge's verdict distribution shifts beyond threshold
7. Full dashboard — exposes stats, calibration, drift alerts, and feedback history via MCP tools

Project Structure

PLTM/
├── mcp_server/
│   ├── pltm_server.py              # MCP server — 136 tools, dispatch + handlers
│   └── handlers/                   # Extracted handler modules
│       ├── registry.py             # Shared component registry (no circular imports)
│       ├── memory_handlers.py      # Typed memory CRUD handlers
│       └── intelligence_handlers.py# Decay, clustering, audit, provenance handlers
├── src/
│   ├── memory/
│   │   ├── memory_types.py         # TypedMemoryStore — 4 memory types, decay, FTS
│   │   ├── embedding_store.py      # EmbeddingStore — async vector search
│   │   ├── memory_intelligence.py  # Decay, consolidation, clustering, conflicts, provenance
│   │   ├── memory_jury.py          # 3-judge validation gate + meta-judge
│   │   ├── memory_pipeline.py      # 3-lane conversation processing pipeline
│   │   ├── attention_retrieval.py  # Attention-weighted atom retrieval
│   │   └── knowledge_graph.py      # Graph operations on atoms
│   ├── analysis/
│   │   ├── epistemic_monitor.py    # Core epistemic tools (V1)
│   │   ├── epistemic_v2.py         # Advanced epistemic + persistent identity (V2)
│   │   ├── pltm_self.py            # Self-modeling system
│   │   ├── data_ingestion.py       # Knowledge ingestion (URL, arXiv, Wikipedia, RSS)
│   │   ├── fact_checker.py         # Claim verification against sources
│   │   ├── grounded_reasoning.py   # Evidence-based synthesis
│   │   ├── model_router.py         # Multi-LLM routing (Groq, DeepSeek, Ollama)
│   │   ├── goal_manager.py         # Persistent goal tracking
│   │   ├── task_scheduler.py       # Cron-like task scheduling
│   │   ├── state_persistence.py    # Cross-conversation state
│   │   └── ...                     # 18 modules total
│   ├── storage/
│   │   └── sqlite_store.py         # SQLite graph store with FTS + WAL mode
│   └── core/                       # Data models, config
├── deep-claude-dashboard/
│   ├── src/App.jsx                 # React dashboard (Vite + Tailwind + Recharts)
│   ├── api_server.py               # Dashboard API server (serves built assets in prod)
│   └── vite.config.js              # Build config with production support
├── tests/
│   └── test_typed_memory.py        # Unit tests (11 passing)
├── scripts/                        # Utility scripts
├── data/
│   └── pltm_mcp.db                # Knowledge base (40 tables)
├── setup_pltm.py                  # One-command setup (venv, deps, DB, model)
├── configure_claude.py            # Auto-configure Claude Desktop
├── health_check.py                # Verify installation
├── backfill_embeddings.py          # Batch embedding indexer
├── migrate_atoms_to_typed.py       # Atom → typed memory migration
├── requirements.txt                # Full dependencies
├── requirements-lite.txt           # Lite dependencies (no torch)
└── README.md

Database

The database (data/pltm_mcp.db) is created automatically on first run. It starts empty and grows as Claude learns:

• 40 tables — typed_memories, memory_embeddings, personality snapshots, prediction book, calibration cache, confabulation log, session history, goals, provenance, meta-judge events, and more
• Full-text search via FTS5 on both atoms and typed memories
• WAL mode enabled on all connections to prevent "database is locked" errors
• Portable — copy the DB to another machine and Claude picks up the same identity

The more you use it, the richer Claude's memory becomes. In the dev instance, the DB has grown to 1,600+ atoms and 1,650+ typed memories.

Dashboard

A React-based dashboard for visualizing the memory system:

cd deep-claude-dashboard
npm install
npm run dev          # Dev server on http://localhost:3000
# In another terminal:
python api_server.py # API server on http://localhost:8787

Production mode:

npm run build        # Build to dist/
python api_server.py # Serves both API and built dashboard on :8787

Dashboard tabs:

• Overview — Atom count, claim accuracy, intervention stats
• Claims — Prediction book with resolution tracking
• Personality — Communication style, curiosity, values
• Evolution — Personality changes over time
• Atoms — Browse and search knowledge atoms
• Memory Intelligence — Health audit, type distribution, decay forecast, importance ranking, clusters, jury stats, conflicts, typed memory browser

Testing

# Run all typed memory tests
python -m pytest tests/test_typed_memory.py -v

# 11 tests covering:
#   store & get, all 4 memory types, jury rejection,
#   query by type, query by tags, min_strength filtering,
#   decay curves, stats, FTS search, belief updates,
#   procedural outcome recording

Environment Variables

Troubleshooting

"MCP server not connecting"

1. Check the path in claude_desktop_config.json is absolute and correct
2. Verify Python: .venv/bin/python3.11 -c "import mcp; print('ok')"
3. Test server directly: PYTHONPATH=. .venv/bin/python3.11 -m mcp_server.pltm_server
4. Check Claude Desktop logs for errors

"Import errors"

source .venv/bin/activate
pip install -r requirements-lite.txt

"Tools not showing up"

• Restart Claude Desktop after config changes

"Database empty on new machine"

• Make sure you pulled data/pltm_mcp.db from git
• If missing: git lfs pull or re-clone

"Tool timeout / No result received"

• Embedding model loads lazily on first use — first call may take a few seconds
• All embedding operations are async (non-blocking) to prevent timeouts
• WAL mode is enabled to prevent "database is locked" errors

License

MIT

Author

Alby (@Alby2007) — 2026