TIMPs v1.0 — Trustworthy Interactive Memory Partner System

A professional memory system that understands, recalls, and evolves with you.

Quick Start • Features • Commands • TUI Guide • Roadmap

What is TIMPs?

TIMPs is an AI-powered memory partner that:

• Understands your context and learns from conversations
• Remembers important facts and patterns across sessions
• Retrieves memories when relevant using semantic search
• Evolves by reflecting on retrieved memories
• Interfaces via beautiful TUI (Terminal UI) or CLI
• Isolates memories by project to prevent contamination
• Performs dual-search (SQL + vectors) for accuracy

System Overview

TIMPs is a v1.0 production-ready AI agent system featuring:

• Premium TUI Interface: Professional 4-panel terminal UI with blessed
• Memory-First Architecture: 14-field schema with project isolation
• Dual Search: SQL (ILIKE) + Vector (Qdrant) semantic search
• Model-Agnostic Design: Pluggable interface for OpenAI, Gemini, and Ollama
• Safe Deletion: Confirmation-required commands with preview
• Ephemeral Mode: Temporary conversations for sensitive topics
• CLI & REST API: Multiple interfaces for integration

Architecture

sandeep-ai/
├── main.ts                 # CLI entrypoint, --tui routing
├── package.json            # Dependencies (blessed, pg, @qdrant/js-client)
├── tsconfig.json           # TypeScript config
├── .env                    # Configuration
│
├── api/                    # Express REST handlers
│   ├── routes.ts          # API endpoints
│   └── server.ts          # HTTP server
│
├── config/                # Configuration management
│   ├── env.ts             # Type-safe env loading
│   └── index.ts           # Config exports
│
├── core/                  # AI Agent logic
│   ├── agent.ts           # Main agent class (robust JSON parsing)
│   ├── executor.ts        # Task execution
│   ├── planner.ts         # Planning logic
│   ├── reflection.ts      # Memory extraction & scoring
│   └── index.ts           # Exports
│
├── db/                    # Database layer
│   ├── postgres.ts        # PostgreSQL (14-field schema)
│   ├── vector.ts          # Qdrant integration
│   └── index.ts           # Exports
│
├── interfaces/
│   ├── cli.ts             # CLI commands (!blame, !forget, !audit)
│   ├── tui.ts             # Blessed TUI (4-panel layout) 
│   └── tuiHandlers.ts     # Reusable command handlers
│
├── memory/                # Memory system
│   ├── embedding.ts       # Vector generation
│   ├── index.ts           # Memory index
│   ├── longTerm.ts        # Persistent storage
│   ├── shortTerm.ts       # Session cache
│   └── memoryIndex.ts     # Memory manager (composite keys)
│
├── models/                # LLM providers
│   ├── baseModel.ts       # Interface
│   ├── openaiModel.ts     # OpenAI adapter
│   ├── geminiModel.ts     # Gemini adapter
│   ├── ollamaModel.ts     # Ollama adapter
│   └── index.ts           # Provider factory
│
├── tools/                 # External tools
│   ├── baseTool.ts        # Tool interface
│   ├── fileTool.ts        # File access
│   ├── webSearchTool.ts   # Web search
│   └── index.ts           # Exports
│
├── QUICKSTART.md          # 5-minute setup guide
├── TUI_README.md          # Full TUI documentation
└── README.md              # This file

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Ollama or OpenAI API (for LLM)
• Qdrant (optional, can use SQL-only)

Quick Start

1. Install Dependencies

cd sandeep-ai
npm install

2. Start Services

# Terminal 1: PostgreSQL
brew services start postgresql  # macOS
# or: sudo systemctl start postgresql  # Linux

# Terminal 2: Ollama (recommended for local)
ollama serve
ollama pull mistral  # or llama2, neural-chat

# Terminal 3: Qdrant (optional)
docker run -p 6333:6333 qdrant/qdrant

3. Configure Environment

Edit .env:

PROVIDER=ollama
OLLAMA_API_URL=http://localhost:11434
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=sandeep_ai
POSTGRES_USER=postgres
POSTGRES_PASSWORD=yourpassword
QDRANT_URL=http://localhost:6333

4. Initialize Database

npm run init-db

5. Launch TUI

npm run tui -- --user-id 1

You're done! See Full Setup Guide

Usage

TUI Mode (Recommended)

# Default
npm run tui -- --user-id 1

# With username
npm run tui -- --user-id 1 --username "Developer"

# Ephemeral mode (no persistence)
npm run tui -- --user-id 1 --mode ephemeral

# Different model
npm run tui -- --user-id 1 --provider openai

CLI Mode (Scripts/Automation)

npm run cli -- --user-id 1 --interactive

Commands

!blame <keyword>

Search for memories containing keyword:

> !blame TypeScript

🔍 Found 2 memory item(s):
  [2] REFLECTION ⭐⭐⭐⭐⭐ favorite language is TypeScript
  [1] EXPLICIT ⭐⭐ TypeScript helps catch bugs early

!forget <keyword>

Delete memories with confirmation:

> !forget React

⚠️ Found 1 memory - preview:
  [1] React is my favorite UI framework

Delete? [Y/n]: Y
✅ Deleted 1 memory

!audit

Show last 10 memories with metadata:

> !audit

📋 AUDIT LOG
[2] REFLECTION ⭐⭐⭐⭐⭐
    favorite language is TypeScript
    Created: 2/16/2026, 6:47:52 PM | Retrieved: 1x

[1] EXPLICIT ⭐⭐
    React is my favorite UI framework  
    Created: 2/16/2026, 6:50:15 PM | Retrieved: 0x

REST API

# Chat endpoint
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "username": "User",
    "message": "I like TypeScript"
  }'

# Get memory
curl http://localhost:3000/api/memory/1

# Get goals  
curl http://localhost:3000/api/goals/1

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PROVIDER | LLM provider (ollama/openai/gemini) | ollama | | OLLAMA_API_URL | Ollama server URL | http://localhost:11434 | | OPENAI_API_KEY | OpenAI API key | - | | GEMINI_API_KEY | Gemini API key | - | | POSTGRES_HOST | Database host | localhost | | POSTGRES_PORT | Database port | 5432 | | POSTGRES_DATABASE | Database name | sandeep_ai | | POSTGRES_USER | Database user | postgres | | POSTGRES_PASSWORD | Database password | - | | QDRANT_URL | Vector store URL | http://localhost:6333 | | NODE_ENV | Environment | development | | PORT | API server port | 3000 |

Database Schema

memories table (14 fields):

CREATE TABLE memories (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT NOT NULL,
  project_id VARCHAR(255) NOT NULL,
  content TEXT NOT NULL,
  memory_type ENUM('explicit', 'reflection'),
  importance INT (1-5),
  retrieval_count INT DEFAULT 0,
  last_retrieved_at TIMESTAMP,
  source_conversation_id UUID,
  source_message_id BIGINT,
  tags VARCHAR(255)[],
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE UNIQUE INDEX idx_project ON memories(user_id, project_id);
CREATE INDEX idx_updated ON memories(updated_at DESC);

Database Schema

The system automatically creates these tables:

• memories - Long-term memories (14 fields)
• users - User accounts
• conversations - Chat sessions
• messages - Individual messages
• goals - User goals
• preferences - User preferences
• projects - User projects

Performance

| Operation | Time | Notes | |-----------|------|-------| | Store memory | 150ms | Async PostgreSQL + Qdrant | | SQL search | 10ms | Indexed by (user_id, project_id) | | Vector search | 50ms | Qdrant, top-10 results | | Merge results | 5ms | Deduplication in-memory | | Total !blame | ~65ms | Sequential: SQL + vec + merge | | Reflection | 1-5s | LLM-dependent | | TUI render | <30ms | Per frame |

Troubleshooting

| Issue | Solution | |-------|----------| | "Cannot connect to database" | Check PostgreSQL: brew services start postgresql | | "Cannot find module 'blessed'" | Run: npm install | | "TUI doesn't render" | Try: export TERM=xterm-256color | | "No response from Ollama" | Check: curl localhost:11434/api/tags | | "JSON parsing error" | Fixed in v1.0 ✅ | | "!blame finds nothing" | Use !audit to verify memories exist |

Extending the System

Keyboard Shortcuts (TUI)

| Key | Action | |-----|--------| | Enter | Send message | | Ctrl+L | Show audit log | | Tab | Switch panels | | Ctrl+C | Exit | | ↑/↓ | Scroll history | | hjkl | Vim navigation |

Contributing

Pull requests welcome! Areas that need help:

• [x] TUI implementation (completed v1.0)
• [ ] Web UI dashboard
• [ ] Docker Compose setup
• [ ] Performance optimizations
• [ ] Additional LLM providers
• [ ] Tool system expansion

License

MIT