Open Source · Local-First · v0.1.4
The institutional memory layer for AI-assisted development.
Decisions, lessons, patterns, regressions — captured in markdown,
stored in your repo, owned by you.
npm install -g ithos ithos-mcp
The Problem
AI writes code faster than teams can absorb it. Git records what was built — but the reasoning, rejected alternatives, and hard-won lessons vanish into ephemeral chat windows and scattered threads. Weeks later, even the original author can't explain why.
Core Pillars
Your memory lives locally inside .ithos/. No external databases, SaaS subscriptions, or internet required.
Memory files participate in branches, commits, merges, and pull reviews. They move with your code.
Frontmatter-enhanced Markdown. Fully readable in VS Code, Cursor, Obsidian, GitHub, or a terminal.
Your AI assistant drafts memory files via MCP as you code. You review and approve.
records what changed
Commits, diffs, and blame tell you which lines were modified and by whom.
preserves why it changed
Decisions, tradeoffs, lessons, and rejected alternatives — the reasoning behind the code.
How It Works
Your AI assistant captures decisions, lessons, and session logs via MCP — structured, frontmatter-tagged, and saved to .ithos/.
Search memory with ithos search or let your AI assistant automatically query past decisions when solving a bug or making a change.
Run ithos timeline to see the project's full institutional history unfold chronologically — like watching the project remember itself.
Timeline
$ ithos timeline 2026-07-02 Decision Use Prisma over TypeORM → Better migrations and developer experience → Schema-driven client with strong TypeScript inference ↳ .ithos/decisions/use-prisma-over-typeorm.md ──────────────────────────────────────────────────── 2026-07-05 Lesson Avoid nested transactions → Caused connection pool exhaustion under load → Use sequential queries with explicit savepoints instead ↳ .ithos/lessons/avoid-nested-transactions.md ──────────────────────────────────────────────────── 2026-07-08 Regression Auth middleware broke guest routes → Middleware applied globally instead of per-route → Fixed by splitting into authenticated and public pipelines ↳ .ithos/regressions/auth-middleware-guest-routes.md Session Implemented MCP server → Created search_memory capability → Integrated with Cursor and Claude Desktop ↳ .ithos/sessions/implement-mcp-server.md ──────────────────────────────────────────────────── 2026-07-13 Decision Institutional Memory over Engineering Memory → Better captures the organizational, durable nature of the concept ↳ .ithos/decisions/institutional-memory-terminology.md 5 entries across 4 days
Repository Layout
.ithos/.ithos/ ├── README.md # Memory overview for AI agents & developers ├── project.md # Project context, stack, conventions ├── decisions/ # Engineering decisions with tradeoffs ├── architecture/ # Structural changes and ADRs ├── features/ # Feature records and capabilities ├── patterns/ # Reusable patterns and conventions ├── lessons/ # Post-mortems, bug resolutions ├── regressions/ # Regressions and context ├── defects/ # Defect records ├── gaps/ # Known gaps and deferred work ├── releases/ # Release notes and milestones └── sessions/ # Developer session outcomes
Get Started
$ npm install -g ithos $ ithos init
Creates the .ithos/ structure in your project root.
$ npm install -g ithos-mcpAdd to your AI client config and restart your editor.
{
"mcpServers": {
"ithos": {
"command": "ithos-mcp"
}
}
}$ ithos timelineWatch the project's institutional memory unfold.
CLI Reference
| Command | Description |
|---|---|
ithos init | Initialize the .ithos/ directory |
ithos validate | Verify repository structure matches the spec |
ithos doctor | Inspect local setup and diagnose issues |
ithos record | Record a decision, lesson, session, or other artifact |
ithos search <query> | Search across all institutional memory |
ithos export | Export the full memory directory to stdout |
ithos timeline | Chronological timeline of all institutional memory |
Architecture
┌──────────────┐
│ Future App │
└──────┬───────┘
│
┌─────────────┐ │ ┌──────────────┐
│ Ithos CLI │ │ │ MCP Server │
└──────┬──────┘ │ └──────┬───────┘
│ ▼ │
│ ┌───────────┐ │
└──►│ Core │◄──┘
└─────┬─────┘
│
▼
┌─────────────┐
│ Local FS │
└─────────────┘
Domain logic: init, validate, record, search, export, timeline. Every consumer reuses this — zero duplication.
Thin CLI. Renders core output with colors and icons. Contains no business logic.
MCP stdio server. AI assistants call it to query and record memory in real-time.
Principles
Everything exists to preserve institutional memory.
No internet, no cloud. Your data lives in your repo.
Indexes and databases are secondary and always derived.
Merges and PR reviews are the synchronization mechanism.
AI handles the grunt work. Developers own the knowledge.