Aleph

A CLI exocortex that is token efficient and connects your knowledge bases to AI agents.

Comment

Inspiration

Every developer I know loses hours not to bad tools: but to forgetting and also not coordinated their agents/dealing with context bloat. Why did I write this function? What was I building toward at 2am last Tuesday? Why did I abandon that approach? The modern developer lives across three or four disconnected surfaces: a notes app (Obsidian), a memory/web system (Strix), AI coding agents like Claude Code and OpenRouter models, and a terminal. None of these surfaces talk to each other in any meaningful way. We don't need another app what we need instead is something that lives between them all and remembers everything you don't. That's what Aleph is.

The name comes from Borges' short story where the Aleph is the single point in space that contains all other points. That's exactly what this tool tries to be.

What It Does

Aleph is a terminal-native exocortex: a Ratatui TUI built in Rust that sits at the center of your knowledge Base stack. Concretely it:

  • Pairs with your Obsidian vault directly via the local Markdown filesystem (no plugins, no Obsidian CLI dependency): reads, writes, and syncs notes bidirectionally
  • Syncs with Strix: your AI memory platform — pulling in saved memories and notes into a unified local session
  • Routes AI queries through OpenRouter, letting you /ask, /agent edit notes with natural language, with diffs shown before any write is approved
  • Serves an MCP server (/serve mcp) so AI agents like Claude Code and Codex can connect to Aleph as a memory and knowledge tool directly
  • Manages a local memory layer — you can /memory save, /memory search, and /recall recent activity entirely offline
  • Path/Idea Forking — decision points in your workflow are snapshotted so you can branch your thinking like git branches, exploring alternate reasoning paths without losing your current thread and connect this with a repo too to branch out based on ideas/thoughts and coordinate this with agents.

How We Built It

  • Language: Rust for performance and correctness in a terminal environment
  • TUI framework: Ratatui + Crossterm for the terminal interface
  • Networking: reqwest (blocking + rustls-tls) for Strix API calls and OpenRouter AI completions
  • Storage: keyring for secure credential storage (Strix token, OpenRouter key), local JSON for notes and memories
  • Obsidian integration: direct Markdown filesystem access + obsidian:// URI scheme for vault discovery and open-in-Obsidian actions — no plugin required
  • Architecture: split across src/app.rs (state machine + command handler), src/ui.rs (rendering layer), src/app/commands.rs (command registry), and src/app/model.rs (data types), dual-mode: full TUI or headless CLI piping via cargo run -- <command>

Challenges We Ran Into

  • Keychain portability — keyring behaves very differently across Linux secret services, macOS Keychain, and Windows Credential Store; required fallback config-dir logic for environments without a keychain daemon
  • Obsidian vault discovery — Obsidian doesn't expose a stable CLI API; had to reverse-engineer the obsidian.json desktop config format to locate vaults reliably across platforms
  • Async vs blocking in a TUI — Ratatui's render loop is synchronous; AI completions and Strix sync calls are blocking network operations. Managing this without freezing the UI required careful threading architecture
  • Path/Idea Forking state serialization — snapshotting the full cognitive state (notes, memories, AI context, active thread) at arbitrary decision points required designing a serialization format that was fast, diffable, and human-readable

Accomplishments That We're Proud Of

  • A truly zero-dependency Obsidian integration — no plugin, no Obsidian CLI, no third-party API. Just the filesystem and URI scheme. This makes Aleph work with any Obsidian vault out of the box
  • Dual-mode CLI/TUI from a single binary — cargo run for the interactive session, cargo run -- note list for scripting and piping into other tools
  • MCP server built into the TUI — Aleph exposes itself as an MCP tool, meaning Claude Code and Codex can use Aleph as a live memory and knowledge source mid-coding session
  • Shipping v0.1 and v0.2 within a single week of active development, going from scaffold to a fully functional multi-provider AI + sync TUI
  • 60fps terminal UI that actually feels fast and fluid — not the sluggish, flickery experience most Rust TUIs ship with

What We Learned

  • Rust's ownership model is genuinely painful for stateful TUI applications, but the resulting code is remarkably robust; we had zero memory bugs once it compiled
  • Building a TUI is easy as well as hard. We hold a lot of respect for Codex CLI and OpenCode devs now.

What's Next for Aleph

  • Intent Threads — every action tagged with a why vector, not just a what, building visible chains of purpose across days of work
  • The Residue Layer — surfacing abandoned work (deleted notes, closed branches, half-finished thoughts) when they become contextually relevant again
  • Ideas/Plans Forking UI — a visual branch explorer in the TUI for navigating decision-point snapshots (we already have the TUI functional but we want to make it as good as git but it works on something as general as text and can combine text and ideas with LLMs without adding slop or rewriting)

Built With

Share this project:

Updates