Symbiotic AI: Plain Markdown Memory for Claude Code and Hermes Agents

The problem Symbiotic AI is aimed at: agent memory you cannot read

Most agent memory is a feature of the platform you happen to be using. The README states the contrast directly: native platform memory is "opaque, automatic, and locked to one vendor." You cannot open it, diff it, or move it to a different model. If you switch tools, the accumulated context stays behind.

Symbiotic AI takes the opposite position. Your identity, commitments and current direction are stored in a handful of Markdown files that live in a git repository you clone. The README's opening line is the whole thesis: "Your AI's context should belong to you, not a platform." The project describes itself as a reference implementation of a broader idea it calls thinking loops, hosted at thinkingloops.makestudio.app, which is a separate site from the tool itself.

The audience is narrow and identifiable. This is for people who already run a coding agent from a terminal and are comfortable with git, because the entire system is a repository plus a small set of conventions. It is not a product with a login. The README points people who want a chat-based setup at the Personal AI Hub at symbiotic.makestudio.app, and offers a paid one-to-one screen-share setup, which tells you the manual path is expected to be done by the user.

Four files, one read at session start, one write as you work

The mechanism is deliberately small. Four files sit at the root of the repository, and the README gives each one a purpose and a change cadence.

SOUL.md holds agent personality, identity, values and how it thinks and talks, and the README says it changes monthly. USER.md holds your profile: identity, psychology, wiring, mission and energy patterns, also monthly. AGENTS.md covers how the agent operates, including protocols, tools, patterns and interventions, and changes weekly. NOW.md is the current state: tasks, queue, log, active projects and deadlines, changing daily.

The data flow is stated in one sentence: "The agent reads all 4 at session start. Updates NOW.md as you work." That is the entire loop. There is no database, no embedding index, no background sync. The system is Shell and Markdown, and the top-level repository listing confirms it: alongside the four Markdown files you find commands/, skills/, guides/, examples/, install.sh and a .obsidian/ directory, which suggests the author opens the vault in Obsidian.

The README makes a claim about why this compounds: the system gets smarter over time "not because of AI improvements, but because the files accumulate real context about you." That is an honest framing. The value is in the writing, not in a model upgrade.

NOW.md also carries a dated memory log. The README shows entries with a date heading and a short observation, including a quoted line from a real conversation and a repeated pattern noted across three weeks. This is the part that most distinguishes the system from a scratchpad: the log is meant to be reread and to surface repetition.

Installing Symbiotic AI and getting a first session out of it

The README gives a fastest start through the GitHub CLI. It installs a skill called symbiotic-onboard, which runs a short interview and then writes your files.

gh skill install lout33/symbiotic-ai symbiotic-onboard

After that, you invoke symbiotic-onboard inside your agent and answer the questions. The README points to guides/getting-started.md for the full walkthrough and a manual path. Note that gh skill is not a command the README explains further, so check that your GitHub CLI version provides it before assuming this route.

The recommended runtime is Hermes. The README's sequence installs Hermes, clones the repository as your workspace, optionally copies SOUL.md into a global location, and then starts the agent from inside the workspace.

# 1) Install Hermes Agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc  # or: source ~/.zshrc

# 2) Clone your Symbiotic workspace
git clone https://github.com/lout33/symbiotic-ai ~/symbiotic-ai
cd ~/symbiotic-ai

# 3) Optional but recommended: use the Symbiotic voice globally in Hermes
mkdir -p ~/.hermes
cp SOUL.md ~/.hermes/SOUL.md

# 4) Start Hermes from inside the workspace
hermes

The placement rules matter. SOUL.md becomes the global voice at ~/.hermes/SOUL.md, while AGENTS.md, USER.md and NOW.md stay in the workspace or project root. The README warns that if you already have a ~/.hermes/SOUL.md, you should merge rather than overwrite it.

For Claude Code or opencode, the README offers a quick installer that pipes a script into bash.

curl -fsSL https://raw.githubusercontent.com/lout33/symbiotic-ai/main/install.sh | bash

The manual route is two commands and no surprises.

git clone https://github.com/lout33/symbiotic-ai
cd symbiotic-ai

Once running, the README lists slash commands including /start-day for a morning kickoff that sets a most-important-task, /check-day for a quick accountability check-in, /end-day for an evening review that captures wins and lessons, and /reflect for deeper reflection. The commands table in the README is truncated mid-entry, so treat the full command set as something to read in the repository's commands/ directory rather than from the README alone.

Where Symbiotic AI is the wrong tool

The honest limitation is that nothing here is enforced by software. The agent reads four files because the instructions say to. If your model ignores AGENTS.md, or your session starts outside the workspace directory, the context is simply absent and you may not notice until the output feels generic.

There is no licence file in the repository listing. The README does not state terms, and the project metadata records the licence as unknown. If you work somewhere that requires a known licence before adoption, that is a blocker until the author adds one, and it is not something to resolve by assumption.

The README's own evolution timeline is a warning about expectations. Week one and two are filling in files. Month one is when the agent starts noticing patterns. Month two and beyond is when optional files appear. Anyone hoping for immediate capability gains from a git clone will be disappointed, because the mechanism is accumulation.

There is also a privacy dimension the README does not address. USER.md is described as holding your psychology, mission and energy patterns, and the memory log example contains a candid personal observation about avoiding a call. These are plain files on your disk, which is the point, but they are also exactly the kind of content you should think about before committing to a public repository or syncing to a shared machine. The README does not document an encryption story or a redaction workflow.

Finally, the README does not document rollback. If an agent writes something into NOW.md that you did not want, the recovery mechanism is whatever git gives you, and nothing in the README describes a review step before writes land.

How it differs from native platform memory and from CLAUDE.md-style setups

The README includes a comparison table against native platform memory across three axes. Ownership: the vendor owns it and it lives in their account, versus you owning plain Markdown on your disk. Portability: locked to one platform, versus running on any model, with Claude Code, Hermes, OpenClaw and opencode named. Transparency: opaque and automatic, versus every line readable, editable and deletable.

The more interesting comparison is with the single instruction file pattern that Claude Code users already have. A CLAUDE.md file is static guidance you write once and revise occasionally. Symbiotic AI splits that role across four files with different change cadences, and adds NOW.md as a file the agent is expected to write to during the session. The difference in approach is that one file describes standing rules, while this system separates standing rules from current state and keeps a dated log of observations. Whether that separation earns its overhead depends on whether you actually review the log.

The README also points to a multi-agent hierarchy guide for scaling past one main agent, describing a human to orchestrator to leads to specialists pattern. That is a documented extension, not a default.

Maintenance cost, release history and the licence gap

The repository is not archived, and the last push was on 2026-06-26, which is the same date as the v1.0.0 release. That is the only release listed. Treat the project as stable but not frequently changing, and check the repository before assuming a fix has landed for anything you hit.

Upgrade cost is low by construction. There is no package to update and no service to restart. Pulling new commits and reading the diff is the upgrade. The real maintenance burden is editorial: SOUL.md and USER.md are meant to be refined monthly, AGENTS.md weekly, and NOW.md daily. That is a writing habit, not an ops task, and it is the part that decides whether the system works.

The licence question is unresolved. The repository listing shows no LICENSE file and the metadata records the licence as unknown. The README does not discuss terms of use, redistribution or commercial use. If you need a clear licence before adopting a dependency, this is the first thing to raise with the author, and it is a question for your own compliance process rather than something this article can settle.

Editorial conclusion

Adopt Symbiotic AI if you already run Claude Code, Hermes or opencode and you want agent context stored as Markdown you can read, edit and commit, with a documented 1.0.0 release from 2026-06-26 and a last push on 2026-06-26. Do not adopt it if you expect a packaged runtime, a licence statement, or memory that updates itself without you editing files; the repository carries no licence file and the README does not document rollback. Before relying on it, verify what install.sh writes to your home directory, confirm the gh skill install lout33/symbiotic-ai symbiotic-onboard path works against your GitHub CLI version, and check the licence question with whoever owns your compliance process.

Frequently asked questions

Official sources

1. Issues
2. lout33/symbiotic-ai on GitHub
3. Project website
4. README
5. Releases