PLTM — Persistent Long-Term Memory for Claude

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

<details> <summary><strong>Alternative: manual clone + setup</strong></summary>

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

The setup script handles everything: venv, deps, .env, DB, model, and Claude Desktop config.

Flags:

• --skip-claude — skip Claude Desktop auto-config
• --skip-model — skip embedding model download (faster)
• --reset — delete venv + DB and start fresh
• --uninstall — remove PLTM from Claude Desktop config

</details>

<details> <summary><strong>Fully manual setup</strong></summary>

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

Then edit your Claude Desktop config:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

Restart Claude Desktop.

</details>

---

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.

Tool	Description
store_episodic	Store an episodic memory (events, experiences) with emotional valence
store_semantic	Store a semantic memory (facts, knowledge)
store_belief	Store a belief with confidence and evidence tracking
store_procedural	Store a procedural memory (trigger → action patterns)
recall_memories	Type-aware retrieval with strength/tag filtering
search_memories	Full-text search across all typed memories (FTS5)
semantic_search	Embedding-based similarity search (384-dim vectors)
what_do_i_know	Cross-type synthesis for a topic
update_belief	Update belief confidence with new evidence
record_procedure_outcome	Track success/failure of procedural memories
correct_memory	Correct a memory's content with audit trail
forget_memory	Explicitly delete a memory
auto_prune	Remove decayed memories below strength threshold
auto_tag	Auto-tag all memories for a user
find_similar	Find memories similar to a given memory (embedding)
index_embeddings	Batch-index all memories for embedding search
memory_stats	Get typed memory statistics by type
detect_contradictions	Find contradicting memories
user_timeline	Chronological memory timeline
get_relevant_context	Pre-fetch conversation-relevant memories

Memory Intelligence (12+ tools)

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

Tool	Description
process_conversation	3-lane pipeline — auto-extracts memories from conversation messages
pipeline_stats	Pipeline throughput statistics
apply_memory_decay	Apply time-based strength decay to memories
decay_forecast	Forecast which memories will decay below threshold
consolidate_memories	Merge similar episodic memories into semantic knowledge
contextual_retrieve	Retrieve memories relevant to current conversation context
rank_by_importance	Rank memories by composite importance score
surface_conflicts	Detect conflicting beliefs/memories
resolve_conflict	Resolve a detected memory conflict
memory_clusters	Build similarity-based memory clusters
memory_provenance	Get provenance chain for a memory (source, pipeline stage, jury verdict)
memory_audit	Full health audit of the memory system
apply_confidence_decay	Evidence-based confidence decay for beliefs

Memory Sharing & Portability (4 tools)

Tool	Description
share_memory	Share a memory with another user
shared_with_me	List memories shared with you
export_memory_profile	Export all memories as portable JSON
import_memory_profile	Import a memory profile (with merge support)

Knowledge Graph & Retrieval (30+ tools)

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

Tool	Description
store_memory_atom	Store a semantic triple (subject, predicate, object)
attention_retrieve	Attention-weighted retrieval with domain filtering
mmr_retrieve	Diversity-aware retrieval (Maximal Marginal Relevance)
attention_multihead	Multi-head attention across knowledge base
bulk_store	Batch store multiple atoms
query_pltm_sql	Direct SQL queries against the knowledge base

Knowledge Ingestion (6 tools)

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

Tool	Description
ingest_url	Scrape and extract knowledge from any URL
ingest_arxiv	Batch search and ingest arXiv papers
ingest_wikipedia	Extract knowledge from Wikipedia articles
ingest_rss	Monitor RSS feeds for new knowledge
ingest_text	Extract triples from raw text
ingest_file	Process local files

Epistemic Monitoring (14 tools)

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

Tool	Description
auto_init_session	Persistent identity loader — loads personality, goals, calibration at conversation start
end_session	Personality snapshot — captures who Claude is for evolution tracking
check_before_claiming	Pre-response confidence check with historical calibration
calibrate_confidence_live	Real-time calibration with suggested phrasing
log_claim / resolve_claim	Prediction book for tracking claim accuracy
get_calibration	Calibration dashboard by domain
extract_and_log_claims	Auto-detect factual claims in responses
suggest_verification_method	Recommend how to verify a claim
generate_metacognitive_prompt	Internal self-questioning before risky claims
analyze_confabulation	Post-mortem on why a confabulation happened
get_session_bridge	Cross-conversation continuity context
get_longitudinal_stats	Personality evolution — tracks changes over time

Self-Modeling (7 tools)

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

Tool	Description
learn_communication_style	Track verbosity, hedging, jargon, tone
track_curiosity_spike	Detect genuine vs performative engagement
detect_value_violation	Record value boundary encounters
evolve_self_model	Track self-predictions vs actual behavior
track_reasoning_event	Log confabulations, verifications, error catches
self_profile	Query accumulated self-data
bootstrap_self_model	Seed personality from conversation transcripts

Fact-Checking & Grounded Reasoning (7 tools)

Tool	Description
verify_claim	Check a claim against source material
fetch_arxiv_context	Get relevant arXiv context for verification
verification_history	Review past verifications
synthesize_grounded	Cross-domain synthesis requiring evidence
evidence_chain	Build evidence chains for claims
calibrate_confidence	Grade confidence based on evidence strength
audit_synthesis	Audit a synthesis for unsupported claims

Goal Management (3 tools)

Tool	Description
create_goal	Create a goal with success criteria
update_goal	Update progress on a goal
get_goals	List active goals

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

Type	Description	Decay Rate	Example
Episodic	Events and experiences	Fast (hours–days)	"User debugged a Python async issue on Feb 10"
Semantic	Facts and knowledge	Slow (weeks–months)	"Python's GIL prevents true parallelism"
Belief	Opinions with evidence tracking	Evidence-based	"AI will surpass humans at coding by 2030" (confidence: 0.6)
Procedural	Trigger → action patterns	Success-weighted	"When user says 'deploy' → run the CI pipeline"

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

Variable	Required	Description
GROQ_API_KEY	Yes (for LLM tools)	Free at console.groq.com
DEEPSEEK_API_KEY	No	For DeepSeek model routing
PYTHONPATH	Yes (in Claude config)	Must point to the PLTM repo root

---

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