┌─────────────────────────────────────────────────┐
│              MCP Transport (stdio)               │
│         9 core tools + graph tools               │
├─────────────────────────────────────────────────┤
│              REST API (HTTP)                      │
│     /api/memories  /api/analytics  /api/events   │
├─────────────────────────────────────────────────┤
│              Service Layer                        │
│  MemoryService, EntityService, SearchService,    │
│  ConsolidationService, EmbeddingService          │
├─────────────────────────────────────────────────┤
│              Repository Layer                     │
│  MemoryRepo, EntityRepo, RelationRepo            │
├─────────────────────────────────────────────────┤
│         Database (PostgreSQL + pgvector)          │
│         or (SQLite + sqlite-vec + FTS5)          │
└─────────────────────────────────────────────────┘

CREATE TABLE memories (
    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    external_id UUID UNIQUE NOT NULL DEFAULT gen_random_uuid(),
    content TEXT NOT NULL,
    memory_type VARCHAR(50) NOT NULL DEFAULT 'observation',
    tags TEXT[] DEFAULT '{}',
    confidence DECIMAL(3,2) NOT NULL DEFAULT 1.00,
    importance DECIMAL(3,2) DEFAULT 0.50,
    source VARCHAR(100),
    context TEXT,
    metadata JSONB DEFAULT '{}',
    embedding VECTOR(384),
    access_count INTEGER DEFAULT 0,
    last_accessed_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- Indexes
CREATE INDEX idx_memories_type ON memories(memory_type);
CREATE INDEX idx_memories_tags ON memories USING GIN(tags);
CREATE INDEX idx_memories_confidence ON memories(confidence);
CREATE INDEX idx_memories_created ON memories(created_at);
CREATE INDEX idx_memories_metadata ON memories USING GIN(metadata);

CREATE INDEX idx_memories_embedding ON memories
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

CREATE TABLE entities (
    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    external_id UUID UNIQUE NOT NULL DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    entity_type VARCHAR(100) NOT NULL,
    description TEXT,
    metadata JSONB DEFAULT '{}',
    embedding VECTOR(384),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(name, entity_type)
);

CREATE INDEX idx_entities_type ON entities(entity_type);
CREATE INDEX idx_entities_name ON entities(name);

CREATE TABLE relations (
    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    external_id UUID UNIQUE NOT NULL DEFAULT gen_random_uuid(),
    source_id BIGINT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
    target_id BIGINT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
    relation_type VARCHAR(100) NOT NULL,
    strength DECIMAL(3,2) NOT NULL DEFAULT 0.50,
    confidence DECIMAL(3,2) NOT NULL DEFAULT 1.00,
    context TEXT,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(source_id, target_id, relation_type)
);

CREATE INDEX idx_relations_source ON relations(source_id);
CREATE INDEX idx_relations_target ON relations(target_id);
CREATE INDEX idx_relations_type ON relations(relation_type);

CREATE TABLE entity_memories (
    entity_id BIGINT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
    memory_id BIGINT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
    relevance DECIMAL(3,2) DEFAULT 1.00,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    PRIMARY KEY (entity_id, memory_id)
);

CREATE TABLE memory_versions (
    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    memory_id BIGINT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
    content TEXT NOT NULL,
    confidence DECIMAL(3,2),
    metadata JSONB,
    version_number INTEGER NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_versions_memory ON memory_versions(memory_id);

-- FTS5 virtual table
CREATE VIRTUAL TABLE memories_fts USING fts5(
    content,
    memory_type,
    tags,
    context,
    content=memories,
    content_rowid=id
);

-- Triggers to keep FTS in sync
CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
    INSERT INTO memories_fts(rowid, content, memory_type, tags, context)
    VALUES (new.id, new.content, new.memory_type,
            (SELECT group_concat(value) FROM json_each(new.tags)),
            new.context);
END;

CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
    INSERT INTO memories_fts(memories_fts, rowid, content, memory_type, tags, context)
    VALUES ('delete', old.id, old.content, old.memory_type,
            (SELECT group_concat(value) FROM json_each(old.tags)),
            old.context);
END;

CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
    INSERT INTO memories_fts(memories_fts, rowid, content, memory_type, tags, context)
    VALUES ('delete', old.id, old.content, old.memory_type,
            (SELECT group_concat(value) FROM json_each(old.tags)),
            old.context);
    INSERT INTO memories_fts(rowid, content, memory_type, tags, context)
    VALUES (new.id, new.content, new.memory_type,
            (SELECT group_concat(value) FROM json_each(new.tags)),
            new.context);
END;

CREATE VIRTUAL TABLE memory_vectors USING vec0(
    memory_id INTEGER PRIMARY KEY,
    embedding FLOAT[384]
);

interface EmbeddingProvider {
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
    dimensions: number;
    modelName: string;
}

SELECT id, content, 1 - (embedding <=> $1::vector) AS similarity
FROM memories
WHERE 1 - (embedding <=> $1::vector) > $2
ORDER BY embedding <=> $1::vector
LIMIT $3;

SELECT memory_id, distance
FROM memory_vectors
WHERE embedding MATCH $1
ORDER BY distance
LIMIT $2;

confidence(t) = initial_confidence × 0.5^(t / half_life)

Where:
  t = time since last_accessed_at (or created_at if never accessed)
  half_life = 30 days (configurable)

SELECT id, content,
    confidence * POWER(0.5, EXTRACT(EPOCH FROM (NOW() - COALESCE(last_accessed_at, created_at))) / (30 * 86400))
    AS effective_confidence
FROM memories
WHERE /* effective_confidence > threshold */;

SELECT id, content, ts_rank(to_tsvector('english', content), plainto_tsquery('english', $1)) AS rank
FROM memories
WHERE to_tsvector('english', content) @@ plainto_tsquery('english', $1)
ORDER BY rank DESC
LIMIT $2;

SELECT m.id, m.content, f.rank
FROM memories_fts f
JOIN memories m ON m.id = f.rowid
WHERE memories_fts MATCH $1
ORDER BY f.rank
LIMIT $2;

hybrid_score = α × keyword_score + (1 - α) × semantic_score

Default α = 0.4 (semantic-weighted)

{
    "entities": [
        {
            "name": "string (required)",
            "entity_type": "string (required)",
            "description": "string (optional)",
            "metadata": "object (optional)"
        }
    ]
}

{
    "relations": [
        {
            "source": "string (entity name, required)",
            "target": "string (entity name, required)",
            "relation_type": "string (required)",
            "strength": "number 0-1 (optional, default 0.5)",
            "confidence": "number 0-1 (optional, default 1.0)",
            "context": "string (optional)"
        }
    ]
}

{
    "relations": [
        {
            "source": "string (required)",
            "target": "string (required)",
            "relation_type": "string (required)"
        }
    ]
}

{
    "total_memories": 1234,
    "total_entities": 56,
    "total_relations": 78,
    "memories_by_type": {"observation": 500, "decision": 200, ...},
    "average_confidence": 0.72,
    "oldest_memory": "2025-01-01T00:00:00Z",
    "newest_memory": "2026-03-08T12:00:00Z",
    "low_confidence_count": 45
}

POST   /api/memories              Create memory (same params as store_memory)
GET    /api/memories              List memories with filters
GET    /api/memories/:id          Get single memory
PUT    /api/memories/:id          Update memory
DELETE /api/memories/:id          Delete memory
GET    /api/memories/search       Search (query params: q, mode, types, tags, limit)
POST   /api/memories/consolidate  Trigger consolidation

POST   /api/entities              Create entity
GET    /api/entities              List entities
GET    /api/entities/:id          Get entity with relations
PUT    /api/entities/:id          Update entity
DELETE /api/entities/:id          Delete entity
GET    /api/entities/:id/graph    Get entity subgraph
GET    /api/entities/:id/memories Get entity's memories

POST   /api/relations             Create relation
GET    /api/relations             List relations
DELETE /api/relations/:id         Delete relation

GET    /api/analytics/overview    Memory statistics
GET    /api/analytics/growth      Growth over time (memories per day/week/month)
GET    /api/analytics/types       Distribution by memory type
GET    /api/analytics/tags        Tag frequency
GET    /api/analytics/confidence  Confidence distribution histogram

GET    /api/events                SSE stream

{
    "mcpServers": {
        "memory": {
            "command": "node",
            "args": ["path/to/server.js"],
            "env": {
                "DATABASE_URL": "postgresql://user:pass@localhost:5432/memory",
                "DATABASE_BACKEND": "postgres"
            }
        }
    }
}

TEST: Store basic memory
  Call store_memory(content="User prefers TypeScript", memory_type="preference")
  EXPECT: Memory created with id, confidence=1.0, embedding generated

TEST: Store memory with entity association
  Call store_memory(content="Alice manages the frontend team", entity_names=["Alice", "Frontend Team"])
  EXPECT: Memory created, entities auto-created if not existing, entity_memories rows created

TEST: Exact duplicate detection
  Store "User prefers dark mode" twice
  EXPECT: Second call returns existing memory, no duplicate created

TEST: Near-duplicate detection
  Store "User prefers dark mode"
  Store "The user likes dark mode" (semantic similarity > 0.95)
  EXPECT: Second memory merged into first, tags combined, confidence boosted

TEST: Update memory
  Create memory, then update content
  EXPECT: Content updated, new version record created, embedding re-generated

TEST: Delete memory cascades
  Create memory associated with entities
  Delete memory
  EXPECT: Memory deleted, entity_memories rows deleted, entities preserved

TEST: Keyword search
  Store memories about "machine learning" and "web development"
  Search "machine learning"
  EXPECT: ML memory returned, web dev memory not returned

TEST: Semantic search
  Store "canine behavior training tips"
  Search "how to train dogs" with mode=semantic
  EXPECT: Memory returned based on semantic similarity

TEST: Hybrid search combines results
  Store 10 varied memories
  Search with mode=hybrid
  EXPECT: Results reflect both keyword and semantic relevance

TEST: Filter by memory type
  Store observation, decision, and pattern memories
  Search with memory_types=["decision"]
  EXPECT: Only decision-type memories returned

TEST: Filter by tags
  Store memories with various tags
  Search with tags=["typescript", "frontend"]
  EXPECT: Only memories containing ALL specified tags

TEST: Filter by confidence
  Store memories, wait for some to decay
  Search with min_confidence=0.5
  EXPECT: Only memories with effective confidence >= 0.5

TEST: Pagination
  Store 50 memories
  Search with limit=10, offset=20
  EXPECT: Results 21-30 returned

TEST: Initial confidence
  Store memory without explicit confidence
  EXPECT: confidence = 1.0

TEST: Confidence decay over time
  Store memory, simulate 30 days passing
  Query effective confidence
  EXPECT: ~0.5 (half-life = 30 days)

TEST: Confidence decay at 60 days
  Store memory, simulate 60 days
  EXPECT: ~0.25

TEST: Access reinforcement
  Store memory, simulate 15 days, then access it
  EXPECT: last_accessed_at updated, confidence boosted by 0.1

TEST: Confidence cap at 1.0
  Store memory with confidence 0.95, access it
  EXPECT: confidence = 1.0, not 1.05

TEST: Prune low-confidence memories
  Store memories, simulate long decay below threshold
  Run pruning job
  EXPECT: Memories with effective confidence < 0.05 deleted

TEST: Create entity
  Create entity(name="Alice", entity_type="person", description="Software engineer")
  EXPECT: Entity created with embedding

TEST: Create relation
  Create entities Alice and Bob
  Create relation(source="Alice", target="Bob", relation_type="collaborates_with", strength=0.8)
  EXPECT: Relation created, lookup by entity names succeeds

TEST: Duplicate relation prevention
  Create same relation twice
  EXPECT: Unique constraint error or upsert

TEST: Get entity graph (depth=1)
  Create A→B, A→C, B→D
  Get graph for A with depth=1
  EXPECT: Returns A, B, C (not D)

TEST: Get entity graph (depth=2)
  Same setup
  Get graph for A with depth=2
  EXPECT: Returns A, B, C, D

TEST: Entity deletion cascade
  Create entity with relations
  Delete entity
  EXPECT: Entity deleted, relations cascade-deleted, associated memories preserved

TEST: Auto-create entities from store_memory
  Call store_memory with entity_names=["NewPerson"]
  EXPECT: Entity "NewPerson" auto-created with type "unknown"

TEST: Cluster detection
  Store 5 memories about "React hooks" with slight variations
  Run consolidation with threshold=0.85
  EXPECT: Cluster detected, memories merged into primary

TEST: Dry run
  Same setup, run with dry_run=true
  EXPECT: Report generated but no changes applied

TEST: Version trail
  Merge two memories
  EXPECT: Version record created for the absorbed memory

TEST: Entity reassignment
  Memory A associated with Entity X
  Memory B associated with Entity Y
  Merge A into B
  EXPECT: B now associated with both X and Y

TEST: POST /api/memories
  Send valid memory JSON
  EXPECT: 201 Created with memory object

TEST: GET /api/memories/search?q=test
  EXPECT: 200 with array of matching memories

TEST: SSE event on memory creation
  Connect to /api/events, then create memory via API
  EXPECT: Receive memory_created event with memory data

TEST: GET /api/analytics/overview
  EXPECT: 200 with stats object containing counts and averages

Input: query string, search filters
Step 1: Run keyword search → results_kw with BM25 scores
Step 2: Run semantic search → results_vec with similarity scores
Step 3: Normalize keyword scores to [0,1] via min-max
Step 4: Normalize semantic scores to [0,1] (already in this range)
Step 5: Union all memory IDs
Step 6: For each ID:
  - If in both: score = α × kw_norm + (1-α) × vec_norm
  - If keyword only: score = α × kw_norm
  - If vector only: score = (1-α) × vec_norm
Step 7: Sort by score descending
Step 8: Apply effective confidence as final multiplier:
  final_score = hybrid_score × effective_confidence

function getSubgraph(startEntity, maxDepth, minStrength):
    visited = Set()
    queue = [(startEntity, 0)]
    nodes = []
    edges = []

    while queue not empty:
        (entity, depth) = queue.pop(0)
        if entity in visited or depth > maxDepth:
            continue
        visited.add(entity)
        nodes.push(entity)

        for relation in entity.outgoing + entity.incoming:
            if relation.strength >= minStrength:
                edges.push(relation)
                neighbor = relation.other_end(entity)
                if neighbor not in visited:
                    queue.push((neighbor, depth + 1))

    return {nodes, edges}

function checkDuplicate(newContent):
    // Exact check
    hash = sha256(newContent)
    existing = db.query("SELECT * FROM memories WHERE sha256(content) = ?", hash)
    if existing: return {type: "exact", memory: existing}

    // Semantic check
    embedding = embed(newContent)
    similar = db.query(
        "SELECT *, 1-(embedding <=> ?) AS sim FROM memories WHERE 1-(embedding <=> ?) > 0.95 LIMIT 1",
        embedding, embedding
    )
    if similar: return {type: "near", memory: similar}

    return null

function effectiveConfidence(memory):
    lastActive = memory.last_accessed_at ?? memory.created_at
    elapsedDays = (now() - lastActive).totalDays
    halfLife = config.CONFIDENCE_HALF_LIFE_DAYS  // 30
    return memory.confidence * Math.pow(0.5, elapsedDays / halfLife)

project_root/
├── src/
│   ├── index.ts              # Entry point, server setup
│   ├── config.ts             # Configuration loading
│   ├── database/
│   │   ├── schema.ts         # Table definitions
│   │   ├── migrations/       # Schema migrations
│   │   ├── sqlite.ts         # SQLite implementation
│   │   └── postgres.ts       # PostgreSQL implementation
│   ├── models/
│   │   ├── memory.ts         # Memory type/interface
│   │   ├── entity.ts         # Entity type/interface
│   │   └── relation.ts       # Relation type/interface
│   ├── services/
│   │   ├── memory.ts         # Memory CRUD + dedup
│   │   ├── entity.ts         # Entity CRUD
│   │   ├── search.ts         # Search dispatch (keyword/semantic/hybrid)
│   │   ├── consolidation.ts  # Dedup + merge engine
│   │   ├── embedding.ts      # Embedding generation
│   │   └── decay.ts          # Confidence management
│   ├── mcp/
│   │   ├── server.ts         # MCP tool registration
│   │   └── tools.ts          # Tool implementations
│   ├── api/
│   │   ├── router.ts         # Express routes
│   │   ├── middleware.ts      # Auth, logging, error handling
│   │   └── sse.ts            # Server-Sent Events
│   └── utils/
│       ├── hash.ts           # SHA-256 hashing
│       └── normalize.ts      # Text normalization
├── tests/
├── migrations/
└── package.json