Symbiotic AI: Markdown Files as Portable Agent Memory
A symbiotic AI agent that remembers everything, challenges you, and extends your cognition.
At a glance
- What is it?
- Symbiotic AI is a Shell-based reference implementation that keeps an AI agent's context in four plain Markdown files rather than a vendor's memory store. The trade-off is that you maintain the files yourself, and the repository does not state a licence.
- Who is it for?
- Adopt Symbiotic AI if you already run Claude Code, Hermes, opencode or OpenClaw and want your agent's context to be files you can git diff and carry between models. Skip it if you want memory that maintains itself, or if you need a stated licence before shipping it inside a product.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 81 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: Context That Lives in Someone Else's Account
Native platform memory is described in the README as opaque, automatic, and locked to one vendor. You cannot read what was stored, you cannot edit it, and you cannot move it to a different model. For an engineer who switches between Claude Code, opencode, Hermes and OpenClaw, that means every switch resets the relationship with the assistant.
Symbiotic AI takes the opposite position. The README states the goal directly: "Your AI's context should belong to you, not a platform." The unit of storage is a Markdown file on your disk. You can open it in an editor, commit it, branch it, or delete a line you disagree with.
The audience is narrow and specific. It is for people who already drive an agent from a terminal or an IDE plugin, who are willing to spend an interview session writing down who they are, and who treat their own working patterns as data worth keeping. It is not aimed at someone who wants a chat product to remember their preferences without being asked.
Four Files and a Read Order
The mechanism is a fixed set of four files, each with a stated update cadence. SOUL.md holds agent personality, identity, values, and how it thinks and talks, and the table says it changes monthly. USER.md holds your profile: identity, psychology, wiring, mission, energy patterns, also monthly. AGENTS.md holds how the agent operates: protocols, tools, patterns, interventions, changing weekly. NOW.md holds current state: tasks, queue, log, active projects, deadlines, changing daily.
The data flow is simple. According to the README, the agent reads all four at session start and updates NOW.md as you work. There is no database, no embedding index, no retrieval service. The context is whatever fits in those files and whatever the model can hold in its window.
That is the whole architecture, and it is worth being blunt about the consequence: the system does not get smarter because the software improves. The README says so itself, noting the system improves "not because of AI improvements, but because the files accumulate real context about you." Growth is a function of your logging discipline, not of a model upgrade.
The NOW.md log is the part with the most texture. The README shows dated entries recording behaviour rather than tasks, for example an entry noting that a user call was avoided and rescheduled twice, with the pattern labelled as building being safe and talking being scary. A later entry records a quote from the first call. A third confirms a pattern after three weeks spent on a feature nobody asked for. This is a journal format, not a task tracker, and it is the mechanism by which the agent can push back with specifics instead of generic encouragement.
Installation Paths: Hermes, the One-Line Script, or a Plain Clone
There are three documented routes. The README labels Hermes as recommended. It installs Hermes with a curl piped to bash from the NousResearch repository, sources your shell rc file, clones the Symbiotic workspace to ~/symbiotic-ai, optionally copies SOUL.md to ~/.hermes/SOUL.md for a global voice, and then you run hermes from inside the workspace. The README warns that if ~/.hermes/SOUL.md already exists you should merge rather than overwrite.
The file placement rule matters. SOUL.md goes to the global Hermes path. AGENTS.md, USER.md and NOW.md stay in the workspace or project root, and you start the agent from that directory so it picks up current context.
The second route is a quick installer script: curl -fsSL https://raw.githubusercontent.com/lout33/symbiotic-ai/main/install.sh | bash, described as working for Claude Code and opencode. The third is a manual git clone followed by cd into the directory.
There is also a skill-based path. The fastest start installs an onboarding skill with gh skill install lout33/symbiotic-ai symbiotic-onboard, then you invoke symbiotic-onboard inside your agent and answer an interview. The README points to guides/getting-started.md for the full walkthrough and a manual alternative. A hosted option at symbiotic.makestudio.app generates the files through a chat interface with no terminal, and a paid one-to-one screen-share setup is offered through a buymeacoffee link.
The commands table lists four slash commands: /start-day for a morning kickoff that sets the MIT for the day, /check-day for a quick accountability check-in, /end-day for an evening review capturing wins and lessons, and /reflect for deeper reflection. The README text is truncated mid-description of /reflect, so the full behaviour of that command is not documented in the material available here.
Where It Breaks: Maintenance Cost and Missing Metadata
The clearest limitation is that the system depends on you. Four files with four different update cadences means the value degrades the moment you stop writing. A stale NOW.md gives the agent a wrong picture of your week, and a stale USER.md means the agent is reasoning about a version of you that no longer exists. Nothing in the repository description suggests an automatic summariser that prunes or compacts these files.
There is a privacy consideration the README does not address. USER.md is described as holding your psychology and energy patterns, and the NOW.md example log contains candid behavioural notes. These are plain files in a git repository. If you push that repository, you are publishing the material. The README recommends versioning the files in git but does not discuss what to exclude.
Context window pressure is the other structural constraint. Four files read at session start consume tokens before any work begins, and they grow over time by design. The README's own evolution timeline puts refinement of SOUL.md and USER.md in the ongoing phase, with no stated size ceiling or splitting strategy. The multi-agent hierarchy guide is referenced for scaling to orchestrator and specialist agents, but the README does not explain how context is partitioned across that hierarchy.
Finally, the licence is listed as unknown. That is a real blocker for anyone who wants to vendor the files or the installer into a commercial product.
Compared With a Memory Service Like mem0
The obvious alternative is a memory layer that extracts and stores facts automatically, such as mem0 or the native memory built into a hosted assistant. The difference is not quality, it is where the extraction decision happens.
A memory service watches a conversation and decides on its own what to persist, usually into a vector store, and returns relevant fragments at query time. You get recall without writing anything. You also get a store you cannot read line by line, and a store tied to whichever SDK and backend you configured.
Symbiotic AI inverts both halves. Extraction is manual: you write the file. Retrieval is not retrieval at all, it is a full read of four documents at session start. That means no embedding pipeline, no vector database, no similarity threshold to tune, and no silent failure where the wrong memory is injected. It also means no automatic capture. If you did not write it down, the agent will not know it.
For a single engineer working with one agent over months, the manual approach is defensible because the act of writing the log is part of the value. For a team deploying an assistant to hundreds of users, a manual file per user is not a workable memory architecture.
What the Repository Does Not Tell You
Several things cannot be confirmed from the supplied material. There is no benchmark, no session count beyond the README's claim of "100+ sessions" in the context of file evolution, and no measured effect on output quality. The claim that the agent challenges you is illustrated with a single quoted exchange, which is an example rather than evidence of a consistent behaviour.
The examples folder contains three filled-in setups, described as a 22-year-old CS student, a 30-year-old mid-level developer, and a 35-year-old marketing manager. These are realistic-looking samples, not case studies with outcomes attached.
The repository is primarily Shell, which is consistent with an installer script and a set of Markdown templates. That also tells you what this is not: there is no server, no daemon, and no runtime that enforces the read-at-session-start behaviour. The behaviour depends on the host agent honouring the convention that these files exist and should be read. The README's compatibility list (Claude Code, Hermes, OpenClaw, opencode) is a statement of intent, and the Hermes path is the only one with a detailed file-placement section.
Release history is thin. v1.0.0 is the only release listed, dated the same day as the last push.
Who Should Take This On
The system fits an individual practitioner who already runs an agent from a terminal, wants the context to survive a switch between models, and is willing to spend ten minutes on the onboarding interview plus a few minutes a day in NOW.md. The Hermes path is the most completely documented, so if you are choosing a host, that is where the instructions are least ambiguous.
It does not fit anyone who wants memory to be invisible, anyone who cannot commit to daily logging, or anyone who needs a licence statement before shipping. If your context contains anything you would not push to a public remote, keep the repository local until you have decided what belongs in USER.md.
Before adopting, verify three things in the repository itself. First, whether a LICENSE file exists at the root, since the metadata says unknown. Second, whether the install.sh script and the gh skill install path both work on your platform, since the README presents them as alternatives without stating which is current. Third, read examples/jamie, examples/sam and examples/morgan in full to judge whether the level of personal detail they contain is a level you are prepared to write down and maintain.
Editorial conclusion
Adopt Symbiotic AI if you already run Claude Code, Hermes, opencode or OpenClaw and want your agent's context to be files you can git diff and carry between models. Skip it if you want memory that maintains itself, or if you need a stated licence before shipping it inside a product. Before committing, open the repository root and confirm whether a LICENSE file exists, since the project metadata lists the licence as unknown.
Community notes