Timps

TIMPS — The AI Coding Agent That Remembers Everything

🏆 Claude Code forgets everything when you close it. TIMPS remembers — forever. 100% free with Ollama • Open source • Runs fully local • No API keys required 🌐 timps.ai

Read in: English • 日本語 • Deutsch • Español • Français • हिन्दी • Português

> TIMPS is a persistent memory layer for AI coding agents. It remembers your codebase, your decisions, your bugs — so Claude, Cursor, Windsurf, or any MCP-compatible agent never makes you re-explain anything. 22-layer memory. 25 intelligence tools. 30-second install. Free.

---

Table of Contents

• [Try It Now (30 seconds)](#try-it-now-30-seconds)
• [Features](#features)
• [How It Works](#how-it-works)
• [Comparison](#comparison)
• [Use Cases](#use-cases)
• [Performance / Benchmarks](#performance--benchmarks)
• [FAQ](#faq)
• [Documentation](#documentation)
• [Workflow Recipes](#workflow-recipes)
• [Contributors](#contributors)
• [Sponsors](#sponsors)
• [Star History](#star-history)
• [Community](#community)
• [License](#license)

---

Try It Now (30 seconds)

npx timps-code "what does this codebase do?"

That's it. No install, no config, no API key. TIMPS analyzes the current directory, builds a memory profile, and returns a rich analysis with context persistence. If you have Ollama running, everything is 100% free and local.

One-line install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/Sandeeprdy1729/timps/main/install.sh | bash

CLI (after install)

npm install -g timps-code
cd your-project
timps "what does this codebase do?"

Auto-detects Ollama if running, or walks you through picking a provider:

timps --provider claude "refactor the auth module"    # Claude
timps --provider gemini "explain the architecture"    # Gemini
timps --provider ollama "quick fix"                   # Free local
timps --provider auto "analyze this codebase"        # Intelligent routing

MCP Server (Claude Code / Cursor / Windsurf)

npm install -g timps-mcp

Then add to ~/.claude.json (Claude Code), .cursor/mcp.json (Cursor), or ~/.config/windsurf/config.json (Windsurf):

{
  "mcpServers": {
    "timps": {
      "command": "timps-mcp"
    }
  }
}

VS Code Extension

Install from the marketplace or:

code --install-extension timps-ai-coding-agent

Full Server + Docker

git clone https://github.com/Sandeeprdy1729/timps
cd timps && docker compose up -d
npm install -g timps-mcp

---

Features

• 🧠 22-layer persistent memory — 9 core layers (Working → HarmonicSheafWeaver) plus 13 advanced layers (EngramLog, ConsolidationEngine, SynapticPruner, ProvenanceForge, SpacedRepetitionForge, ConstitutionalGuard, AuditForge, ProspectiveTrigger, BiasRevealer, ContextVector, RehearsalEngine, SchemaDistorter, ConfidenceCalibrator). Memory survives across sessions, projects, and agent restarts.
• 🔧 25 intelligence tools — 17 original (contradiction detection, burnout prediction, relationship tracking, etc.) plus 8 new (FalseMemoryDetector, ConfidenceCalibrator, SourceAttributor, ConflictResolver, MemoryAuditor, ProspectiveTrigger, BiasRevealer, SchemaInferrer). Every tool is class-based, deterministic (zero Math.random()), and benchmarked.
• 💰 100% free with Ollama — Runs fully local. Zero API keys required. No telemetry. No cloud dependency.
• 🔌 MCP native — Works out of the box with Claude Code, Cursor, Windsurf, Cline, Continue, Goose, OpenCode, and any MCP-compatible agent.
• 🔄 Multi-provider — Claude, GPT, Gemini, DeepSeek, OpenRouter, Ollama, and custom endpoints. Intelligent auto-routing between providers.
• 🧩 VS Code extension — Full editor integration with memory panel, skill composer, and inline intelligence.
• 📱 Multi-surface — CLI agent, MCP server, VS Code extension, Tauri desktop app, and React Native mobile app.
• 🔌 Plugin system — Extend TIMPS with custom plugins. Plugin SDK included.
• 🏗️ Hybrid storage — SQLite for local/lightweight, optional PostgreSQL for teams, Qdrant for vector search.

---

Desktop App (macOS · Windows · Linux)

The TIMPS Desktop app is a cross-platform memory cockpit built with Tauri 2 and React. It visualizes your agent's persistent memory graph, provides a chat interface, and surfaces intelligence alerts from all 25 engines.

Download the latest release from the Releases page and install for your platform:

| Platform | Format | |----------|--------| | macOS (Intel) | .dmg (x86_64) | | macOS (Apple Silicon) | .dmg (aarch64) | | Windows | .msi or .exe installer | | Linux | .deb or .AppImage |

Or build from source:

cd packages/timps-desktop
npm install
npm run tauri:build

First launch: You'll see a "TIMPS is ready" welcome screen. Press ⌘⇧K for the command bar or ⌘⇧N for quick capture.

Key features:

• 🧠 Memory Explorer — Browse semantic, episodic, patterns, and contradictions with filter chips
• 💬 Chat — Conversational interface with inline tool call display and active memory recall panel
• 🔔 Intelligence Alerts — Real-time feed from all 25 intelligence engines with dismiss/snooze
• 🔌 Integrations — Connect GitHub, Telegram, Slack, Claude Code MCP, and more
• 📊 Stats — Memory health score, most-touched files, peak hours, velocity trends
• ⚙️ Settings — Provider selector with visual active-state indicator, memory retention controls

---

How It Works

graph TB
    User["🧑 Developer"] --> CLI["CLI Agent timps-code"]
    User --> VSC["VS Code Extension"]
    User --> MCP["MCP Server timps-mcp"]

    CLI --> Core["Memory Core"]
    VSC --> Core
    MCP --> Core

    subgraph Core["TIMPS Memory Core (22 layers)"]
        L1["L1 Working"]
        L2["L2 Episodic"]
        L3["L3 Semantic"]
        L4["L4 Procedural"]
        L5["L5 ChronosForge"]
        L6["L6 ResonanceForge"]
        L7["L7 EchoForge"]
        L8["L8 SynapseQuench"]
        L9["L9 HarmonicSheafWeaver"]
        L10["L10 EngramLog"]
        L11["L11 ConsolidationEngine"]
        L12["L12 SynapticPruner"]
        L13["L13 ProvenanceForge"]
        L14["L14 SpacedRepetitionForge"]
        L15["L15 ConstitutionalGuard"]
        L16["L16 AuditForge"]
        L17["L17 ProspectiveTrigger"]
        L18["L18 BiasRevealer"]
        L19["L19 ContextVector"]
        L20["L20 RehearsalEngine"]
        L21["L21 SchemaDistorter"]
        L22["L22 ConfidenceCalibrator"]

        L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8 --> L9
        L9 --> L10 --> L11 --> L12 --> L13 --> L14 --> L15
        L15 --> L16 --> L17 --> L18 --> L19 --> L20 --> L21 --> L22
    end

    Core --> Tools["25 Intelligence Tools"]
    Tools --> Storage["Hybrid Storage"]

    Storage --> SQLite["SQLite Local"]
    Storage --> PG["PostgreSQL Team"]
    Storage --> Qdrant["Qdrant Vector"]

    subgraph Providers["LLM Providers"]
        Ollama["Ollama 🌿 Free"]
        Claude
        GPT
        Gemini
        DeepSeek
    end

    Core --> Providers

When you ask TIMPS a question, the request flows through the 22-layer memory system. Each layer enriches the context: Working memory holds the immediate session, Episodic recalls past sessions, Semantic provides knowledge graph relationships, Procedural injects learned workflows, the forge layers (5–9) handle time-series analysis, resonance matching, pattern synthesis, associative recall, and harmonic weaving, and the advanced layers (10–22) add immutable audit trails, provenance tracking, spaced repetition, constitutional guardrails, bias detection, and confidence calibration. The 25 intelligence tools process the enriched context before returning a response that's grounded in everything TIMPS has learned about your codebase.

---

Comparison

| Feature | TIMPS | agentmemory | Claude Code | MemGPT/Letta | Cline | Continue | Cursor | |---|---|---|---|---|---|---|---| | Persistent Memory | ✅ 22 layers | ✅ SQLite | ❌ | ✅ | ❌ | ❌ | ❌ | | 25 Intelligence Tools | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Free (Ollama) | ✅ | ✅ | ❌ | ⚠️ Partial | ❌ | ✅ | ❌ | | MCP Native | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | VS Code Extension | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | Burnout Detection | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Contradiction Detection | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Multi-Provider | ✅ 7 providers | ✅ | ❌ 1 provider | ❌ | ✅ | ✅ | ❌ | | Self-Hosted | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | | Mobile App | 🟡 Experimental | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Plugin System | ✅ | ✅ (skills) | ✅ (sub-agents) | ❌ | ✅ | ❌ | ✅ |

---

Use Cases

• "I use Claude Code and I'm tired of re-explaining my codebase every session." TIMPS persists everything — architecture decisions, bug patterns, API conventions — across sessions, projects, and restarts.
• "I run Ollama locally and want an AI agent that doesn't phone home." TIMPS is 100% local with Ollama. Zero telemetry, zero API calls, zero cloud dependency.
• "I manage a large monorepo and my agent keeps forgetting context." TIMPS's 22-layer memory handles codebases of any size. The forge layers (ChronosForge, HarmonicSheafWeaver) specialize in long-term pattern recognition and cross-file relationship mapping.
• "I want my AI agent to learn from its mistakes." Contradiction detection, burnout prediction, and anomaly scoring let TIMPS identify when it's giving bad advice and avoid repeating errors.
• "I'm building an MCP-powered toolchain and need memory that works across agents." TIMPS is MCP-native. Connect it to Claude Code, Cursor, Windsurf, Cline, Continue, Goose, OpenCode — any MCP client — and share memory across all of them.

---

Memory Architecture

The 22-layer memory system is TIMPS's core differentiating feature. Each layer serves a specific role in persisting and enriching context:

| Layer | Storage | Persistence | Contents | |---|---|---|---| | L1 Working | In-process | Reset on exit | Current goals, active files, recent errors | | L2 Episodic | episodes.json | Disk (append-only) | Conversation summaries, outcomes | | L3 Semantic | semantic.json | Disk (permanent) | Patterns, conventions, decisions | | L4 Procedural | procedural.json | Disk | Workflows, recipes, skills | | L5 ChronosForge | chronos/ | Disk | Causal graph, temporal dependencies | | L6 ResonanceForge | resonance.json | Disk | Pattern harmonics, oscillation model | | L7 EchoForge | echo/ | Disk | Reservoir states, BFS context | | L8 SynapseQuench | In-memory + disk | Cross-layer | Coherence scores, conflict map | | L9 HarmonicSheafWeaver | sheaf/ | Disk | Sheaf Laplacian, cohomology result | | L10 EngramLog | engram.log.jsonl | Disk (append-only) | Immutable hash-chained audit trail | | L11 ConsolidationEngine | In-memory + disk | On demand | Episodic → semantic promotion | | L12 SynapticPruner | memory-meta.json | Disk | Active forgetting by importance | | L13 ProvenanceForge | provenance/ | Disk (permanent) | Source tracking, chain of custody | | L14 SpacedRepetitionForge | In-memory | Runtime | SM-2 scheduling for review | | L15 ConstitutionalGuard | In-memory | Runtime | Low-confidence write prevention | | L16 AuditForge | In-memory | On demand | Weekly memory health reports | | L17 ProspectiveTrigger | prospective-triggers.json | Disk | "When X, surface Y" triggers | | L18 BiasRevealer | In-memory | On demand | Over/under-representation analysis | | L19 ContextVector | context-vectors.json | Disk | State-dependent recall encoding | | L20 RehearsalEngine | rehearsal-items.json | Disk | Spaced retrieval practice | | L21 SchemaDistorter | schema-patterns.json | Disk | Schema-driven distortion detection | | L22 ConfidenceCalibrator | confidence-calibrations.json | Disk | Multi-signal confidence scoring |

Each project gets isolated memory keyed by SHA256 hash of its absolute path. All 22 layers ship in packages/memory-core.

Memory Branches

Memory is scoped per git branch, just like code:

timps --branch auth-refactor "analyze the auth module"

When the branch is merged, memory is merged into main if patterns are generally useful, archived if branch-specific, or discarded if abandoned. Data is never deleted — it moves to an archived/ subtree.

---

Performance / Benchmarks

All 25 intelligence tools are benchmarked continuously against a standardized evaluation suite. Results are tracked per-commit to prevent regression.

| Metric | TIMPS | agentmemory | mem0 | Letta | |---|---|---|---|---| | Recall@5 (LongMemEval-S) | 95% | 95.2% | 72% | 68% | | MRR | 0.82 | 0.882 | 0.71 | 0.65 | | Contradiction Detection | 100% (10/10) | — | — | — | | Intelligence Tools | 100% (25/25) | — | — | — | | Avg Latency (recall) | 17ms | 45ms | 120ms | 200ms | | Scalability (500 facts) | 0.6ms mean / 1ms p95 | — | — | — |

Run the benchmark suite locally:

npx tsx benchmark/index.ts --quick

All tools are deterministic — zero Math.random() calls in the intelligence layer.

---

25 Intelligence Tools

TIMPS ships 25 class-based intelligence tools in packages/memory-core/src/intelligence/, each designed for a specific cognitive function:

| # | Tool | Purpose | |---|---|---| | 1 | AetherWeft | Analyzes code sentiment and emotional patterns in commit messages | | 2 | ApexSynapse | Cross-reference detection between concepts | | 3 | AtomChain | Semantic chunking of large documents | | 4 | BindWeave | Links related facts into knowledge clusters | | 5 | ChronosVeil | Temporal pattern detection and anomaly detection | | 6 | CurateTier | Automatic memory importance scoring | | 7 | EchoForge | Generates analogies and metaphors for concepts | | 8 | ForgeLink | Creates bidirectional links between knowledge nodes | | 9 | GovernTier | Memory access control and policy enforcement | | 10 | LayerForge | Manages hierarchical memory layer transitions | | 11 | NexusForge | Identifies central concepts and hub nodes | | 12 | PolicyMetabol | Extracts and enforces project policies from memory | | 13 | SkillWeave | Composes skills into coherent system prompts | | 14 | SynapseMetabolon | Cross-session pattern synthesis and insight generation | | 15 | TemporaTree | Manages temporal knowledge graphs with decay | | 16 | ArchitectureDrift | Detects drift between documented and actual architecture | | 17 | VelocityTracker | Tracks feature velocity and development patterns | | 18 | FalseMemoryDetector | Flags memories with weak provenance as false-memory risk | | 19 | ConfidenceCalibrator | Calibrates confidence from similarity, reliability, evidence, freshness | | 20 | SourceAttributor | Returns human-readable provenance chain for any memory | | 21 | ConflictResolver | Jaccard + sentiment-flip analysis for contradictory memories | | 22 | MemoryAuditor | Weekly health audit: weak, contradicted, outdated, unsourced | | 23 | ProspectiveTrigger | "When X happens, surface Y" trigger registration | | 24 | BiasRevealer | Over/under-representation analysis in saved memory | | 25 | SchemaInferrer | Auto-extracts typed schemas from episode/semantic stream |

Every tool is deterministic (zero Math.random()), benchmarked, and backed by file-based JSON storage.

---

Swarm Architecture

TIMPS includes a 10-agent swarm that decomposes complex tasks across specialist agents. The fan-out is local — all agents run in-process, not distributed:

| Agent | Job | |---|---| | Product Manager | Requirements decomposition | | Architect | System design and technology selection | | Code Generator | Implementat

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sandeeprdy1729
• Source: Sandeeprdy1729/timps
• License: MIT
• Homepage: https://www.npmjs.com/package/timps

Install and usage instructions live in the source repository linked above.