timps-code

TIMPS Code — Open-Source CLI Coding Agent

A CLI coding agent like Claude Code — runs on Ollama (free, local), has persistent memory across sessions, and is fully open source.

npm install -g timps-code
timps

What makes TIMPS different

Persistent memory. TIMPS remembers your project across sessions using a 22-layer memory system:

• L1 Working — current goal, active files, recent errors (this session)
• L2 Episodic — summaries of past conversations stored to disk (append-only)
• L3 Semantic — facts, patterns, and conventions your project uses (permanent)
• L4 Procedural — reusable workflows and recipes learned from past sessions
• L5 ChronosForge — causal graph tracking decisions and their consequences
• L6 ResonanceForge — harmonic oscillator model for pattern resonance detection
• L7 EchoForge — reservoir computing with BFS context propagation
• L8 SynapseQuench — cross-layer coherence optimizer
• L9 HarmonicSheafWeaver — sheaf-cohomology engine for algebraic contradiction detection
• L10 EngramLog — immutable hash-chained audit trail of all memory operations
• L11 ConsolidationEngine — episodic → semantic memory promotion on demand
• L12 SynapticPruner — active forgetting by importance scoring
• L13 ProvenanceForge — source tracking and chain of custody for every fact
• L14 SpacedRepetitionForge — SM-2 scheduling algorithm for review timing
• L15 ConstitutionalGuard — prevents low-confidence writes to memory
• L16 AuditForge — weekly memory health reports and drift detection
• L17 ProspectiveTrigger — "when X happens, surface Y" conditional recall
• L18 BiasRevealer — over/under-representation analysis across saved facts
• L19 ContextVector — state-dependent recall encoding and retrieval
• L20 RehearsalEngine — spaced retrieval practice scheduling
• L21 SchemaDistorter — Bartlett schema-driven distortion detection
• L22 ConfidenceCalibrator — multi-signal confidence scoring

When you start a new session and say "use the same pattern we always use for API routes", TIMPS knows what you mean.

Runs 100% locally. The default provider is Ollama. No API keys, no data leaving your machine, no monthly bill.

Self-correcting. When a command fails, the agent analyzes the error, fixes its approach, and retries — up to 3 times by default.

Install

npm install -g timps-code

Requirements: Node.js 18+ | For local AI: Ollama

How the agent loop works

flowchart LR
    Input["User input"] --> App["app.ts\nAgentLoop.run()"]
    App --> Agent["agent.ts\n(plan + execute)"]
    Agent --> Tools["25+ Tools\nfile · git · shell · web"]
    Agent --> Memory["22-Layer Memory\nworking · episodic · semantic"]
    Memory -->|"recalled context"| Agent
    Tools -->|"observation"| Agent
    Agent -->|"stream"| TUI["Ink/React TUI\n(src/ui/App.tsx)"]
    Agent -->|"retry × 3 on error"| Agent

    style Memory fill:#dcfce7,stroke:#16a34a
    style Tools fill:#dbeafe,stroke:#2563eb

Usage

# Interactive session (persistent memory, full agent loop)
timps

# One-shot mode
timps "add input validation to src/api.ts"
timps "write tests for the payment module"
timps "explain why src/queue.ts uses a semaphore"

# Specify provider
timps --provider ollama "refactor this"
timps --provider claude "review this PR diff"
timps --provider gemini "suggest architecture improvements"

# Setup wizard (first time)
timps --config

Providers

Provider	Setup	Cost
Ollama (default)	ollama serve	Free
Claude	ANTHROPIC_API_KEY=...	Paid
OpenAI	OPENAI_API_KEY=...	Paid
Gemini	GEMINI_API_KEY=...	Free tier available
OpenRouter	OPENROUTER_API_KEY=...	Pay per use
Hybrid	Ollama + API fallback	Mixed

TIMPS auto-detects Ollama on startup. If Ollama is running, it uses it without any config.

CLI Flags

timps --provider <name>   # claude | openai | gemini | ollama | openrouter | hybrid
timps --model <model>     # e.g. gpt-4o, claude-sonnet-4-5, llama3.1:8b
timps --dir <path>        # set working directory (default: cwd)
timps --config            # run setup wizard
timps --branch <name>     # start from a named memory branch
timps --merge <name>      # merge a memory branch into current context

Slash commands (inside interactive session)

/help           — list all commands
/memory         — show what TIMPS remembers about this project
/todo           — manage task list with the agent
/branch <name>  — snapshot current memory into a named branch
/merge <name>   — merge a memory branch back
/skills         — list and install skills
/mcp            — list connected MCP servers
/git            — git status and diff
/models         — list available Ollama models
/doctor         — diagnose config and connection issues
/clear          — clear session working memory

Tools available to the agent

TIMPS ships with 25 tools. The agent picks them automatically:

Category	Tools
File ops	read_file, write_file, edit_file, multi_edit, patch_file
Search	find_files, search_code, grep
Git	get_git_status, git_diff, git_log, git_commit
Shell	run_bash
Code quality	run_tests, lint, type_check
Reasoning	think, plan
Web	web_search, web_fetch
Task management	todo_create, todo_list, todo_update

Memory system in practice

TIMPS stores memory per-project in ~/.timps/memory/<project-hash>/:

semantic.json     — long-term facts and patterns
episodes.json     — past session summaries (rolling 100)
working.json      — current session state

You can view it with /memory inside a session, or inspect the files directly.

Branching: timps --branch feature-x snapshots the current memory state before you start a risky refactor. timps --merge main merges it back.

Skills system

TIMPS can install reusable skills — small prompt packages that add domain expertise:

# Inside a session:
/skills list       — browse available skills
/skills install react-patterns
/skills install test-driven-development

Skills are stored in ~/.timps/skills/ and injected into the system prompt when relevant.

Connect to TIMPS MCP (optional)

If you're running the full TIMPS server (docker compose up -d from the repo root), you can connect it to Claude Code, Cursor, or Windsurf for persistent memory inside those tools too. See timps-mcp.

Configuration

On first run, TIMPS creates ~/.timps/config.json. You can also set via environment:

ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
OPENROUTER_API_KEY=sk-...
OLLAMA_BASE_URL=http://localhost:11434   # default
OLLAMA_DEFAULT_MODEL=qwen2.5-coder:7b   # default

Only set the keys for providers you actually use. Ollama needs no key.

License

MIT — github.com/Sandeeprdy1729/timps