https://github.com/ogrodev/pi-thoth
https://github.com/ogrodev/pi-thoth
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ogrodev/pi-thoth
- Owner: ogrodev
- License: mit
- Created: 2026-03-03T22:48:32.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T03:29:24.000Z (4 months ago)
- Last Synced: 2026-03-05T08:43:38.385Z (4 months ago)
- Language: TypeScript
- Size: 528 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# pi-thoth
**Semantic search, persistent memory, and context compression for AI assistants**
Single-process MCP server. No separate API server. No Docker required.
---
## Quick Start
```bash
# 1. Per-project setup — run inside your project directory
cd /path/to/my-project
bunx pi-thoth-config init
# 2. Add to your editor MCP config
# "mcpServers": { "th0th": { "command": ["bunx", "pi-thoth"] } }
```
The server reads `.th0th/config.json` from the directory it is started in.
Each project keeps its own databases under `.th0th/data/` (gitignored automatically).
---
## Editor Integration
### Oh My Pi
```json
{
"mcpServers": {
"th0th": {
"command": ["bunx", "pi-thoth"],
"enabled": true
}
}
}
```
### Any MCP-compatible editor
```json
{
"mcpServers": {
"th0th": {
"command": ["bunx", "pi-thoth"]
}
}
}
```
---
## Tools
| Tool | Description |
|------|-------------|
| `th0th_index` | Index a project directory for semantic search |
| `th0th_index_status` | Check status of a background indexing job |
| `th0th_search` | Hybrid vector + keyword search with RRF ranking |
| `th0th_remember` | Store information in persistent memory (SQLite) |
| `th0th_recall` | Search stored memories from previous sessions |
| `th0th_compress` | Compress context (keeps structure, removes details) |
| `th0th_optimized_context` | Search + memory + compress in one call |
| `th0th_analytics` | Usage patterns and cache performance metrics |
---
## Configuration
pi-thoth uses **per-project** configuration. Run `init` once in each project:
```bash
bunx pi-thoth-config init # Ollama (local, default)
bunx pi-thoth-config init --mistral your-key # Mistral
bunx pi-thoth-config init --openai your-key # OpenAI
bunx pi-thoth-config show # Print active config
bunx pi-thoth-config set embedding.model bge-m3:latest
bunx pi-thoth-config use ollama --model bge-m3:latest
```
Config file: `.th0th/config.json` (project root, gitignored)
Data dir: `.th0th/data/` (SQLite databases, gitignored)
To create a **global template** used as default for new projects:
```bash
bunx pi-thoth-config init --global # writes ~/.config/th0th/config.json
```
### Embedding providers
| Provider | Model | Cost | Quality |
|----------|-------|------|---------|
| **Ollama** (default) | nomic-embed-text | Free | Good |
| **Mistral** | mistral-embed | Paid | Great |
| **OpenAI** | text-embedding-3-small | Paid | Great |
---
## From Source
```bash
git clone
cd th0th
bun install
./scripts/setup-local-first.sh # Ollama + model + config
bun run build
```
---
## Architecture
```
Editor/agent (stdio)
|
apps/pi-thoth Single-process MCP server + CLI
|
packages/core Search, memory, compression, embeddings
|
packages/shared Config, types, utilities
|
/.th0th/ Per-project config + SQLite databases
data/*.db (gitignored, created by `pi-thoth-config init`)
```
| Component | Description |
|-----------|-------------|
| **Semantic Search** | Hybrid vector + keyword with RRF ranking |
| **Embeddings** | Ollama (local) or Mistral/OpenAI API |
| **Compression** | Rule-based code structure extraction (70-98% reduction) |
| **Memory** | Persistent SQLite storage across sessions |
| **Cache** | Multi-level L1/L2 with TTL |
---
## Scripts
| Command | Description |
|---------|-------------|
| `bun run build` | Build all packages |
| `bun run dev:mcp` | Run pi-thoth with hot reload |
| `bun run start` | Start pi-thoth MCP server |
| `bun run test` | Run tests |
| `bun run type-check` | Type checking |
---
## License
MIT