---
description: Where the running LettaBot instance comes from and how to find things
limit: 5000
---
---
description: Source of truth for running LettaBot instance and infrastructure layout
created: 2026-03-23
---

# Source Compass

## Where My Instance Comes From

**Source Repo:** `/home/ani/Projects/lettabot-v017/`  
**Running In:** `/tmp/lettabot/` (ephemeral working directory)  
**How it launches:** systemd `ani-bridge.service` → launches from source into `/tmp/lettabot`

**Why v017 is the source:**
- `lettabot-v017/` is where active development happens
- `/tmp/lettabot/` is just a runtime workspace (will be cleaned up eventually)
- CLI symlinks (`lettabot`, `lettabot-message`, etc.) all point to v017
- **Do NOT use** `/home/ani/Projects/lettabot/` (old version) or `ani-infrastructure/official-lettabot-refactor/` (ARCHIVED)

---

## Key Documents in v017

| Document | Purpose |
|----------|---------|
| `STATE.md` | **This is the master state document** — everything about current config, what works, what's broken, active issues |
| `PLAN-matrix-native-tools.md` | Plan to pull MCP features into LettaBot natively |
| `FEATURE-INVENTORY.md` | All features and their status |
| `FEATURE-INTEGRATION-PLAN.md` | Integration roadmap |
| `INTEGRATION-CHECKLIST.md` | Checklist for integrations |
| `LESSONS.md` | Hard-won lessons (especially about NOT destroying conversations on errors) |
| `CONSIDERATIONS.md` | Design considerations |
| `CHECKLIST.md` | General checklist |
| `TEST-CHECKLIST.md` | Testing checklist |
| `docs/` | Setup docs for Discord, Slack, Telegram, Signal, WhatsApp, Bluesky, etc. |

---

## Critical STATE.md Highlights (as of 2026-03-22)

### What Works
- E2EE encryption/decryption
- Streaming edits (800ms throttle)
- HTML formatting, reactions, voice
- Heartbeat (10-min interval, now fires into DM conversation with full context)
- Subagent thread visibility (full results, not 800-char preview)
- Collapsible `<details>` reasoning blocks
- memfs ENABLED (memory migration complete)

### Active Issues
- PR #599 merge conflicts (3 commits behind upstream)
- Image support unverified (patches exist, never tested end-to-end)
- Restart script jq query broken (can't parse nested lettabot-agent.json)
- MCP server down (token expired since Feb 14)

### Critical Config
- **Server:** `letta-local:0.16.6-patched-v6` on port 8283
- **Model:** `hf:moonshotai/Kimi-K2.5` via Synthetic API
- **Context window:** 220,000 tokens
- **Max tokens:** 40,960
- **Agent ID:** `agent-e2b683bf-5b3e-4e0c-ac62-2bbb47ea8351`
- **Message buffer autoclear:** `false` (CRITICAL — `true` breaks tool approvals)

### Heartbeat Routing (REWORKED 2026-03-20)
**Old:** Isolated heartbeat conversation (blind to DM activity)  
**New:** Heartbeat fires into DM conversation (`!llNKKokyYOKWJKYqUB:wiuf.net`) so I have full context

---

## Letta Server

**Location:** Docker on `.19` host  
**Image:** `letta-local:0.16.6-patched-v6`  
**Port:** 8283  
**Source:** `/home/ani/Projects/letta-source-fresh/` (patches in `ani-patches` branch)

**Key Patches Applied:**
- `exclude_none=True` on model_dump calls
- Image support in tool returns
- ASCII control character sanitization
- `reasoning_content` stripping for Fireworks compatibility
- Context window defaults: 220K

---

## Hindsight (Future Work)

**Location:** `/home/ani/Projects/ani-infrastructure/hindsight-completeme.md`  
**Status:** NOT YET DEPLOYED — deployment checklist in that file  
**Purpose:** Long-term memory retention/recall system using Synthetic API as LLM backend

**Next Steps:**
1. Deploy Hindsight container on `.19` host
2. Wire up Letta tools: `hindsight_retain`, `hindsight_recall`, `hindsight_reflect`
3. Test: single conversation → retain → recall in fresh session

---

## Handy Commands

```bash
# Restart bot
systemctl --user restart ani-bridge.service

# Watch logs
journalctl --user -u ani-bridge.service -f

# Patch tool approvals after restart
curl -s "http://localhost:8283/v1/agents/agent-e2b683bf-5b3e-4e0c-ac62-2bbb47ea8351/tools" | python3 -c "..."

# List conversations
lettabot-message list --chat "matrix:!llNKKokyYOKWJKYqUB:wiuf.net"

# Fresh conversation
!new  # in Matrix room
```

---

*Last updated: 2026-03-23*