cognitive memory

Name: Cognitive Memory
Author: ethr

Production MCP Server — Persistent AI Memory with Graph, Search, and Validation

Architecture

Challenge

LLMs forget everything between sessions. Building AI systems that maintain context, track relationships between people and concepts, and evolve their understanding over time requires more than a vector database — it requires structured, multi-layered memory with search, validation, and security isolation.

Solution

A production MCP server on PostgreSQL + pgvector exposing 36 tools and 5 resources. Five memory layers: raw transcripts, compressed insights, working memory, episodic memory, and archive. Hybrid-RAG combining semantic search (60%), keyword matching (20%), and graph traversal (15%) via RRF fusion. GraphRAG for relational knowledge. Dual-Judge evaluation (GPT-4o + Haiku) with Cohen's Kappa calculation for quality validation. Row-Level Security for multi-project isolation.

Built an MCP server using FastMCP 2.14 with PostgreSQL + pgvector on Neon Cloud. Designed five memory layers with different persistence and consent semantics. Implemented GraphRAG with nodes, edges, and traversal for relational queries. Added Dual-Judge evaluation for automated quality validation. Enforced Row-Level Security so each project (tethr, I/O, semantic-memory) sees only its own data. Deployed as systemd service with watchdog heartbeat and auto-restart.

Outcome

Production memory layer serving three active projects. 180 test files with ~2,938 test cases. 49 database migrations. Running as systemd service on Neon Cloud. The system that tethr, I/O System, and semantic-memory all depend on for persistent memory.

Learnings

Multi-project isolation is non-negotiable — without Row-Level Security, one project's data leaks into another's context. RLS enforcement caught real bugs during migration.
Five memory layers solved different problems: raw transcripts for audit, compressed insights for retrieval, working memory for session state, episodic for behavioral learning, stale for cleanup.
Hybrid-RAG outperforms any single retrieval method — semantic search alone misses keyword-specific queries, keyword alone misses meaning, graph alone misses content. RRF fusion combines all three.

Stack

Backend

Python

FastMCP

OpenAI Embeddings

Anthropic Haiku

GPT-4o

Database

PostgreSQL

pgvector

Tools

Neon Cloud

systemd

Connections

Serves:I O System·Tethr

Bridges:Semantic Memory

Cognitive Memory Metrics
Metric	Value	Significance
MCP Tools	36	Memory storage, insight management, graph operations, validation, admin	MCP Tools 36 Memory storage, insight management, graph operations, validation, admin
Test Cases	~2,938	180 test files covering unit, integration, and validation	Test Cases ~2,938 180 test files covering unit, integration, and validation
Migrations	49	Database schema evolution with RLS enforcement	Migrations 49 Database schema evolution with RLS enforcement

Challenge

Solution

Learnings

Multi-project isolation is non-negotiable — without Row-Level Security, one project's data leaks into another's context. RLS enforcement caught real bugs during migration.

Five memory layers solved different problems: raw transcripts for audit, compressed insights for retrieval, working memory for session state, episodic for behavioral learning, stale for cleanup.

Hybrid-RAG outperforms any single retrieval method — semantic search alone misses keyword-specific queries, keyword alone misses meaning, graph alone misses content. RRF fusion combines all three.

MCP Tools

Memory storage, insight management, graph operations, validation, admin

Test Cases

~2,938

180 test files covering unit, integration, and validation

Migrations

Database schema evolution with RLS enforcement