Armedev: blog

I built a second brain in Go - Khayal

Wed, 08 Apr 2026 00:00:00 GMT

I have a problem with note-taking apps.

Not a preference problem. A trust problem.

Every tool I tried either lives on someone else's server, requires an account, or stores my thoughts in a format I do not fully own. Notion is great until Notion decides to change pricing. Obsidian is local but has no capture layer. Mem.ai is clever but completely cloud. And all of them want to be the center of your workflow.

Why not just use Obsidian with a plugin?

Because Obsidian has no capture layer. No CLI. No local LLM processing. No semantic search.

I did not want a center. I wanted a pipe.

So I built Khayal -- a local-first second brain that runs on your machine, processes with your own LLM, and stores everything as plain markdown. No accounts. No cloud. No telemetry. We genuinely do not know if anyone is using it.

خيال - Arabic for imagination, vision, the mind's eye.

Two binaries, not one

This was the first decision and it shaped everything else.

khayal is the server. It owns the database, the worker queue, the Ollama calls, and the embedded PWA. It is the thing you start once and forget about.

kl is the client. It is a thin HTTP wrapper. It knows one thing: where the server is and what the token is. Everything else is the server's problem.

Why not just one binary? Simpler to distribute.

Yeah, and also couples everything together. You cannot update the client without restarting the server. You cannot run the server on one machine and the client on another. The mental model gets muddy fast.

Two binaries is the right call. The added distribution complexity is worth it. This is the hard way and I knew the tradeoffs going in.

The CGo decision

Go's SQLite story is annoying.

The standard driver is mattn/go-sqlite3. It works great. It also requires CGo, which means cross-compilation becomes painful, goreleaser needs a C toolchain, and your Docker builds get complicated.

I did not want any of that. Khayal should be go build and done. So I used modernc.org/sqlite -- a pure Go SQLite port transpiled from the original C. No CGo. No toolchain requirements. goreleaser just works.

The tradeoff is sqlite-vec. The vector extension for SQLite is a C library and it does not play nicely with modernc. So right now Khayal does not have native vector search -- it has FTS5 keyword search and a cosine similarity fallback computed in Go. It works. It is not as fast as a proper vec index. I am still working through this.

If you have solved the sqlite-vec + modernc tension I genuinely want to know. The options I see are a separate vec.db handled by a CGo process, or accepting the pure Go cosine fallback forever. Neither is great.

This is a real open problem and not knowing it upfront would have been a major skill issue.

The search stack

Hybrid search with RRF -- Reciprocal Rank Fusion.

FTS5 handles keyword matching with porter stemming. The embedding model (nomic-embed-text via Ollama) handles semantic similarity. Both produce a ranked list. RRF merges them by taking the reciprocal of each result's rank and summing across both lists.

The result is that kl search "observer effect" finds both exact matches and semantically related notes -- depending on what is in your vault.

FTS5 configuration is where I lost the most time. It is very easy to misconfigure silently. Missing porter stemming, wrong column indexing, UNINDEXED columns that should be indexed -- none of these throw errors, they just quietly degrade your search quality. I found bugs in my own FTS5 setup weeks after I thought it was done.

Search quality is the core feature. Do not defer FTS5 configuration like I did. It is not infrastructure, it is the product.

The PWA is inside the binary

The PWA is embedded in the khayal binary via embed.FS.

One binary, one port, the web interface just works at http://127.0.0.1:1133. No separate static file server. No deployment step. No nginx config. Just start the server and open the browser.

The PWA has an offline capture queue backed by IndexedDB. If the server is down, captures queue locally and sync when it comes back. There is a live pipeline visualization that shows notes moving through the processing stages in realtime.

Getting iOS Safari right was the most tedious part of the whole project.

svh instead of vh for viewport height. The html background color must match the nav bar color or Liquid Glass tinting breaks. @media (display-mode: standalone) needs to override certain layout calculations or you get a gap at the bottom in PWA mode. None of this is documented in one place. You just discover it by breaking things.

Your vault is just a folder

~/Documents/brain/
├── 2026-04-07/
│   └── observer-effect.md
├── 2026-04-06/
│   ├── react-patterns.md
│   └── system-design.md
└── .khayal/

Obsidian can open it directly. Git can version it. Any editor can read it. Khayal is a capture and retrieval layer -- it does not own your data, it just indexes it.

So Khayal replaces Obsidian?

No. They are complementary. Khayal is the pipe, Obsidian is the editor. Use both or neither.

What I would do differently

The worker queue overflow is a real failure mode I underestimated. Under load, if Ollama is slow and captures are coming in fast, the job channel fills up. I have a fix for v1.1 but it should have been in v1.

I would also start FTS5 configuration on day one. It feels like infrastructure so you defer it. Do not do that.

Try it

brew install rawnaqs/tap/khayal
khayal init
khayal start
kl "your first thought"
kl search "thought"

GitHub: https://github.com/rawnaqs/khayal
Site: https://khayal.rawnaqs.io

If you are working on anything local-first or have thoughts on the sqlite-vec problem, open an issue or reach out.

If you have feedback regarding this blog post, click on an issue on GitHub

Making it Hard, and Soft

Sat, 30 Mar 2024 00:00:00 GMT

The title of this blog post is just a peek of what we are going to do today.

Let's get started

Today, we are going to see some tips and tricks regarding the usage of Rust language.

Why are you choosing rust it's a language used by blue hair personalities

I know people often consider Rust to be an extremist language, because many of them are not trying to get things done rather just fighting with a borrow checker by banging the Future on their toes just for simple asynchronous executions.

But, that doesn't mean Rust itself is bad, or it doesn't have potential.

Rust is the middle ground for both competitive coders and Project builders, competitive coding is done by all of them, the opponent is borrow-checker, but the project building is done by only some of them.

Considering you know basics of Rust, let's dive into it…

The match and its magic

Consider you had a task to create a subroutine, which is an initializer for a database client.

^{“db refers to database”}

Ideally you will require a name/namespace, and the host endpoint(with credentials). And tadaww you got yourself a client. In theory, it's just simple.

Now the code part,

here we will be using Surreal as a database and its lib surreal db as our rust client,

use surrealdb::{
    engine::remote::ws::{Client, Ws},
    opt::auth::Root,
    Surreal,
};

#[derive(Clone, Debug)]
pub struct SurrealClient {
    db: Surreal<Client>,
}

impl SurrealClient {
	pub async fn init() -> Option<Self> {
		let surreal_url_host = "127.0.0.1:1000";
		let surreal_username = "root";
		let surreal_pwd = "toor";

		let res = match Surreal::new::<Ws>(surreal_url_host).await {
			Ok(db) => {
				let res = match db.use_ns("skill").use_db("issue").await {
					Ok(_) => {
						db.signin(Root {
							username: surreal_username,
							password: surreal_pwd,
						})
						.await
					}
					e => e,
				};
				res.map(|_| db)
			}
			e => e,
		};

		return match res {
			Err(e) => {
				dbg!(&e);
				println!("error: {}", e);
				None
			}
			Ok(db) => Some(Self { db }),
		};
	}
}

Note: Tokio is used as an async runtime

the above might look like a normal subroutine in the first glance but under the hood if you look closely you would find out that it has slight wisdom to it,

firstly, we have a level of abstraction over a client, some argue it to be good, others argue it to be bad. Nonetheless, it gets things done. In our client we have a field db which is of type Surreal<Client>. Here, Surreal is an Arc pointer to a web-socket client. So it is straight forward.

Then we have our impl block, which has init subroutine to initialize our client with some parameters, really simple.

Then, we have our juiced up magic match expressions, let's understand them one by one,

First match expression accounts for a Result<Client, Error>. Second match expression accounts for a Result<(), Error> which runs only when the first match expression resolves to be ok. Inside our second match expression we have db.signin which also returns Result<(), Error>.

So one would think there are too many conditions to check, here's where the Rust's pattern matcher comes to rescue.

Inside every match expression, we previously accounted for an Ok variant, but there is also another variant in Result, the Error variant.

Info: Result is an Enum in Rust, for more info

Surprise‼ we are not accounting for the Error in every match expression instead we are just returning the Result like e => e.

There are multiple benefits of this,

firstly, we are squashing multiple errors into one without making borrow checker angry. Secondly, we don't care what happens to the underlying expressions, we just bubble up those results. Thirdly, the most important part, we get back a single Result with which we are satisfied in this scenario.

And at last we return an Option type of our client.

But, how will you handle individual error of the Results, is it not a good practice to handle it?

Yeah kinda, it is a good practice to acknowledge the expressions which can result in error, to handle it or not solely depends on the developer.

For e.g., in JS:

let something = '';
JSON.parse(something);

Not knowing that the above expressions might throw an error, is a major skill issue but knowing it and voiding it, is whole different scenario.

Stop making too many abstractions and branching of code, just to make your code come under a good coding practice.

Coding practices are a Myth, they are present to make it easy for developers who have skill issues, understand your code. But, I strive for my code to be efficiently understood by the machine it runs on, not the developer who sees it.

I think I conveyed my point :P

The first part Making it Hard is done.

Now it's time for the second part,

The soft part

If you do know Rust to at least to an extent that you can get things done, then you probably might be thinking the above is just an engineer flexing the match expressions.

Yeah, True!

And also not true here's why,

There is a method called and_then on the Result type, which does all of the above error squashing.

But, here's the point you should not blindly use something other people created without trying it out yourself first. This is where you will actually learn things.

Whenever I try to create something, let it be a simple subroutine, I always make it “by my way”. In this process I will know what tradeoffs I am making and what are the weak points of the subroutine.

Then, even in the future if I try to change it to convince some people on the internet, I will have a full context of what is happening under the hood.

Conclusion

If you are just learning or just new to what you are doing, try to make many mistakes as you can by doing it your way (Hard way).

Mistakes make you think better, they broaden your thinking process.

If you just go the road of Soft way, as long as you are in that fairy tale dream land, you will never encounter the mistakes. Which will result in major skill issue.

Only, when you get proficient in your hard way, you should be deciding to go soft way.

Indeed, with hardships there will be ease.

If you have feedback regarding this blog post, click on an issue on GitHub

My First Blog!

Wed, 06 Sep 2023 00:00:00 GMT

Initial words

Hypermedia is great. This is it, so lets jump right into it.

Pre-build

I liked the content I was used to fed by the social platform ALGORITHMS nonetheless it was worth it BUT it was starting to feel a little annoying in the recent years due to MILK YOUR CUSTOMER analogy by the so called Anti-social social platforms, It was pretty obvious I need to move away from all this so called monitored and monitized social platforms but I need to find a better way to absorb good content so....

I started to think and wander like wild buffaloes run towards a end of the hill not knowing its pitfall and even if they try they cannot stop, falling in it, yeah I am talking about all those communities where you become one of them without yourself ever knowing it.

So I wondered what are the good tools I can use to avoid becoming a part of any community and learn new things and also avoid those creepy algorithms, ads, popups, subscriptions and the list goes on,

Yeah, I chose Blogs like a caveman.

Here is the Interesting part you get to choose your own blogs and avoid any misleader or false content just like some tweets. So I started setting up rss feeds I like and just like that I had this huge list of blog posts I can learn or just read to get things going.

And I thought am I a dummmy because you see I am saying blogs are awesome what year is this? 2010.

Historic Recurrence came into rescue and I thought may be history is trying to repeat itself and why not be part of it, so I started creating this Blog.

Build

I chose to go full on no JS framework mode to create the blog I like with the tools I desire.

So HTML, CSS and JS(~10loc)

(JS was used only to switch themes hahaha classic JS)

I said I did not use JS, but I did use it, only to create HTML files.

Templates

filename: blog-template.html

I laid a bunch of HTML tags and left some unique distinguishable keywords in it so that I can inject the content of my blog post dynamically when I plan to publish a post like this one. I take the markdown file and convert it to HTML and replace the unique tags in template file with it, its that simple.

No it's not, where are your manners about security and threats if you had some malicious content in it.

for the most part, It is right its not advisable to inject content directly in a file and publish it but I know whats in their and the script is only running in my local development mode remember(where I said JS 10loc).

Styling

There are no stylings, content is Information not Animations. There are some properties for the displaying of content with a good font and colors and also the DARK MODE.

Interaction

The only interactions a Blog post should have is scrolling and clicking which is already handled by browser so use IT.

Post build

Now this is the part that is pretty interesting its how I manage to publish future blog posts with it.

Its simple if you think about it, Create a markdown file and run the script to output a HTML file in your public directory and publish it to your repo. Thats it.

With the help of either Github CI/CD or any simple hosting techniques, It can be published in a matter of seconds. That I think is blazingly fast.

Imagine the scenario if you had used a framework, stuck in an endless rat race trying to make it work and perfect because you chose a framework which will without your notice do some breaking changes. Now you have to update the site and also create blogs aghhhhh.

Summary

Yeah I know its not extra-ordinary but do you want to use a extra-ordinary tool which may or may not work in future where there will be different ways to do things just to throw out some HTML files at the end.

No, and also It depends, the main question you have to ask yourself is what is it that you desire?

If you want to create a Thing to just do its Thing then avoid doing other things even though it is a Standard. But if you want to focus on other things apart from your Goals then I think you are a dummmmy