30 Minutes to Give Your Agent Permanent Memory: Can cat, can git, can edit directly — a beginner-friendly tutorial with zero hand-holding

I’ve recently been building agent workflows and had a big realization: agents like Openclaw, Hermes, Claude Code, and Codex don’t actually need larger context windows — what they need is better memory. I spent 30 minutes hooking up persistent memory to my favorite coding agent. No Docker, no vector database cluster. And this time, its brain is a bunch of Markdown files I can open and edit directly.

1. Your Agent Wakes Up Amnesiac Every Day

Anyone who has worked with agents knows this frustration: yesterday it helped you track down a nasty bug, today you start a new session and it remembers nothing about yesterday.

All those decisions, workflows, and the painful lessons you learned — none of them follow the agent. The context is locked inside the previous conversation, and once you close it, it evaporates.

Our first instinct is usually to cram more into the prompt. Dump historical records, user preferences, project background — all into the context window — and pray the model doesn’t forget.

But that approach hits a wall quickly. The window has a limit, tokens cost money, and worse — the “memory” you stuff in is disposable; it vanishes as soon as you close the window.

At the end of the day, what you lack isn’t a bigger prompt — it’s a layer of permanent memory.

In this guide, I’ll walk you through connecting an agent to EverOS, an open-source, local-first memory OS — in about half an hour.

No MongoDB, no Elasticsearch, no full vector database cluster.

The best part? It stores memory as Markdown files you can open, read, and even edit manually. Once you follow along, your agent will have cross-session long-term memory — and that memory is transparent, and yours.

Without further ado, let’s get started.

2. Why EverOS Instead of Rolling Your Own Vector Library

Before we start, let’s take a minute to explain how it’s different from “writing another vector library” — because that determines whether these 30 minutes are worth it.

Most memory solutions are a black box: you feed it text, it spits out vectors and stores them in a database, and when you retrieve, it gives you a bunch of similarity scores.

The problem? When something goes wrong, you have no idea what it actually “remembered” or why it remembered it that way. Debugging is basically guesswork 😂

EverOS takes a different path.

Its storage is a local three‑piece set: Markdown as the single source of truth, SQLite for state and processing queues, LanceDB for vectors, BM25 full‑text indexing, and scalar filtering.

What each component does:

• Markdown as single source of truth — all memory lands as readable, grep‑able, git‑version‑able, Obsidian‑openable .md files
• SQLite — manages state and processing queue
• LanceDB — manages vectors, BM25 full‑text index, and scalar filtering

The key is the first one. Want to know what the agent remembers? Just cat it. Want to correct a wrong memory? Open the editor and delete it. That kind of inspectability is something a black‑box vector library can never give you.

As a quick reference, the official benchmarks aren’t bad either: LoCoMo 93.05%, LongMemEval(-S) 83.00%, HaluMem ~90%+ — all from the official measurements. Judge for yourself, but what really won me over certainly isn’t just the numbers.

In short, your agent’s brain is a bunch of files you can open.

Alright, philosophy done. Let’s get our hands dirty.

Step 1: Environment Setup (≈ 5 minutes)

Three things you need:

1. Python 3.10+, officially recommended 3.12+
2. A high‑performance package manager called uv — EverOS uses it to manage dependencies and virtual environments.
3. Two API keys — by default, one OpenRouter key for LLM and multimodal, one DeepInfra key for vectorization and reranking.

If you haven’t installed uv yet, one command does it:

curl -LsSf https://astral.sh/uv/install.sh | sh

(Installation command provided, but reader should use official instructions)

As for the keys: EverOS is compatible with any endpoint that uses the OpenAI protocol.

So if you already have an OpenAI key, a self‑hosted vLLM, or a local Ollama instance, you can swap out the default providers. I’ll explain how to change the configuration in the next step.

Step 2: Installation & Initialization (≈ 5 minutes)

Two installation methods — choose based on your purpose:

From source (if you want to read the code or modify it):

git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
uv sync

Install as a package (if you just want to use it in your project):

uv pip install everos

After either method, initialize with the same command:

everos init

It will generate a starter .env file. Open it and fill in your two keys:

OPENROUTER_API_KEY=sk-...
DEEPINFRA_API_KEY=...

One quick note — be careful: .env contains your keys, so add it to .gitignore first.

Committing it to the repository is a mistake you’ll regret for half a day.

After filling in the keys, run these two commands to confirm everything is fine:

everos health
everos status

Step 3: Start the Service & Verify (≈ 3 minutes)

Start the service:

everos server start

Leave this terminal running. Open a new terminal and do a health check:

curl http://localhost:8000/health

If everything is normal, you’ll see:

{"status": "ok"}

Once you see that ok, your local memory service is alive.

Quick reminder: the docs say the default port is 8000, but double‑check the actual port when you start it locally — don’t assume.

Now we get to the core of this guide.

Step 4: Your First Memory — Write it, then Retrieve it (≈ 8 minutes) ⭐

The most valuable thing about EverOS is what I call the core loop: write a fact → persist it as a Markdown file → retrieve it through a local index. Let’s run through it completely.

First, write a fact about a user. Pay attention to the user_id — it determines who this memory belongs to. This is also why EverOS can work in multi‑user and multi‑agent scenarios without mixing things up.

Let me be honest here. For the exact invocation method (whether it’s a CLI subcommand or a REST request body) in the 1.0.0 local version, you must refer to the QUICKSTART.md in the repository root. Even the README points to that as the authoritative example. I won’t copy old interface fields that might break your setup. Below is a schematic example; after you get it working, replace it with the actual command from your local environment:

everos memory write --user alice --fact "Alice prefers dark mode in her code editor."

After this write, EverOS does three things behind the scenes: it extracts the sentence into a structured memory, persists it as Markdown, and syncs it into the SQLite and LanceDB local indexes.

Now, simulate being in a “new session the next day” and retrieve it with plain language:

everos memory search --query "What UI theme does Alice like?"

Once it works, paste the actual result you get from your local environment here — it should match the preference above and include a relevance score.

Behind the scenes is a hybrid search: BM25 for keyword matching, vector ANN for semantic matching, scalar filtering for precise slicing by dimensions like user_id — all unified under LanceDB. So even if you rephrase the query, it will still find it.

At this point, your agent already has cross‑session memory. But the thing that excites me most about EverOS is the next step.

Step 5: Open the Black Box — See What Memory Looks Like (≈ 5 minutes) ⭐

Remember the opening line: “the brain is a bunch of files”? Now let’s go find those files.

Open ~/.everos:

cat ~/.everos/users/alice/user.md

You’ll see that the preference you just wrote has been structurally inserted into Alice’s profile — readable by humans, and editable by you.

Yes, literally — your agent’s memory is a note you can open anytime.

This is what “Markdown as the single source of truth” really means.

Even cooler: you can open the entire ~/.everos directory in Obsidian and browse your agent’s memory like a visual knowledge base.

I strongly recommend taking a screenshot of that view — it explains “transparent memory” better than any text ever could.

You might have noticed two lines in the directory: users/ and agents/.

This is exactly EverOS’s dual‑track memory: the user track keeps context and profile (who is the user, what do they like), and the agent track keeps cases and skills (what did the agent do, what did it learn). The two tracks are extracted separately and never pollute each other.

One Step Further — What Else Can It Do

In these 30 minutes we only ran through the core loop, but EverOS can do much more. Let me briefly point out a few directions you can explore on your own.

Multimodal ingestion — a single API call can ingest PDFs, images, documents, tables, and web URLs into memory.

One heads‑up here: Office document parsing depends on LibreOffice being installed on your system. Without it, .docx/.pptx/.xlsx will fail, but PDFs, images, and audio are unaffected.

Self‑evolution — each completed task is recorded as a Case; patterns that repeatedly succeed are promoted into reusable Skills that are shared across the entire agent team, without you having to curate them manually.

On the roadmap are also Knowledge Wiki (turning fragmented memories into versionable wiki pages) and Reflection (connecting weak signals during idle time, compressing history, and improving profiles).

I’m looking forward to those directions, but they’re still in development — consider this a preview.

A Few Common Pitfalls

The biggest gotcha deserves its own mention.

Many “EverOS tutorials” online describe the early heavy version that requires docker-compose up to launch a whole stack of MongoDB, Elasticsearch, and Redis.

If you follow those, you’ll stumble from step one. The entire value of the 1.0.0 lightweight version in this article is precisely that it doesn’t need those — look for commands like everos init / everos server start from the CLI.

Two more quick notes: remember to install LibreOffice for Office document parsing; and definitely add .env to .gitignore.

Conclusion: Memory Is Worth Taking Seriously

Half an hour ago, your agent started from scratch every single session.

Now it has a layer of cross‑session persistent memory — and that memory is not a set of incomprehensible vectors in a black box, but files you can open, read, edit, and version‑control with Git.

That’s why I think it’s worth bookmarking. It didn’t turn “memory” into a vague concept; instead it gave developers something concrete that can run, be inspected, and be modified.

If you’re working on an agent, LLM application, or coding assistant that needs long‑term memory, go ahead and bookmark this repository now. The next time you start a new project, you’ll remember it:

👉 https://github.com/EverMind-AI/EverOS

This article is based on EverOS 1.0.0 lightweight local edition. All benchmarks are from official sources. The repository updates quickly; before publishing, please verify the latest version number, default port, and the authoritative examples for write/retrieve operations in QUICKSTART.md, and replace the schematic commands with the actual commands and outputs from your local environment.