What if AI memory was just Markdown, Git, and rules humans can understand?

I have been working with AI more and more recently.
Like many developers, I have tried different AI coding assistants, agents, prompts and workflows.
And after using them for a while, I started noticing a simple problem.
The AI is very good at working with me today.
But tomorrow, I have to explain many things again.
Why did we choose this architecture?
Why did we reject that library?
What have we already tried?
What is still unfinished?
What decisions did we make yesterday?
The longer the project lives, the more painful this becomes.
So I started thinking about AI memory.
I wanted to try something much simpler.

What if AI memory was something humans could read?

When people talk about AI memory, there are many technical approaches:

• databases
• vector databases
• embeddings
• RAG
• semantic search
• memory services
• cloud APIs

These approaches can be very useful.
But I asked myself a different question:

Does AI memory have to be complicated if all I want is for an AI agent to remember important project context between sessions?

What if the memory was just a Markdown file?
Something like:

.ai-memory/ ├── 2026-08-14.md ├── 2026-08-15.md └── 2026-08-16.md

I can open it.
The AI can read it.
I can edit it.
Git can track it.
I can see exactly what changed.
No special database viewer.
No memory service.
No proprietary format.
Just a file.
And that idea became Lean AI Memory.

The idea

The core idea is very simple:

Human ⇆ Readable Memory ⇆ AI Agent ⇆ Git

The AI and the human share the same project memory.
The memory is stored as Markdown.
Git provides history, diff, branching and collaboration.
The AI can read the memory at the beginning of a session and update it when something important happens.
For example:

2026-08-14

Completed

• Added PDF signature verification. - Added Excel export. ## Decisions
• PDF processing remains local. - SQLite is used for local configuration. ## Problems
• Batch verification is still slow. ## Next
• Investigate batch verification. - Improve error reporting.

Tomorrow, another AI session can read this.
It does not need me to explain everything from scratch.

But memory is only half of the problem

After thinking about it more, I realized something.
Storing memory is easy.
The harder question is:

What should the AI remember?

Should it remember every conversation?
Probably not.
Should it save every line of code?
Definitely not.
Should it remember architectural decisions?
Probably.
What about rejected approaches?
Sometimes.
What about unfinished work?
Definitely.
What about project-specific business rules?
That depends on the project.
And this is where I decided not to hard-code the answer.

Rules should be defined by the user

Lean AI Memory uses a simple rules file.
For example:

AI Memory Rules

Before starting work:

• Read the latest relevant memory. - Check unfinished work. - Check important architecture decisions. When making an important decision:
• Record the decision. - Record why it was made. - Record important alternatives that were rejected. When finishing a work session:
• Record completed work. - Record unresolved problems. - Record what should happen next. Keep memory concise. Do not store the entire conversation.

The important part is:
These rules are not fixed.
You can change them.
A developer may want one type of memory.
A documentation project may need another.
A research project may need something completely different.
A team may have its own conventions.
I don't want Lean AI Memory to pretend that I know what every industry needs.
So I leave the rules open.

The memory format is simple. The rules are yours.

Why Markdown?

Because humans can understand it.
That sounds almost too obvious.
But I think it matters.
Imagine that your AI has remembered an important architectural decision.
Where is it?
Inside a vector database?
Inside embeddings?
Inside some hidden memory service?
Maybe.
But can you open it and understand exactly what the AI remembers?
With Markdown, the answer is simply:
Yes.
You can open the file.

.ai-memory/2026-08-14.md

You can read it.
You can edit it.
You can delete something that should not be remembered.
You can commit it.
You can review the diff.
You can even argue with the AI about its own memory. :)

Why Git?

Because software projects already have a memory system.
It's called Git.
Git already gives us:

• history
• diff
• branches
• merge
• rollback
• collaboration
• local storage
• remote backup

So I don't see a strong reason to build another complicated history mechanism just for AI memory.
If the AI changes its memory:

git diff

can show me what happened.
For example:

• Decision:+ Use PostgreSQL instead of MongoDB.
• Reason:+ Transactional consistency is required.

That is a very useful property.
The AI's memory becomes part of the project's history.

I intentionally kept the project small

This is probably the part that may look strange if you first see the repository.
Lean AI Memory is tiny.
There is no memory server.
There is no database.
There is no vector search engine.
There is no embedding pipeline.
There is no cloud infrastructure.
The core idea is basically:

Markdown+Git+Natural-language rules

That's it.
And this is intentional.
I am not trying to build the most powerful AI memory engine.
I'm trying to answer a smaller question:

Can simple, human-readable project memory be useful enough for AI agents?

I don't know the answer yet.
So I built the smallest thing I could.

It is not about replacing vector databases

I want to make this clear.
I am not saying:

"Vector databases are bad."

Or:

"Embeddings are useless."

They solve different problems.
If you have millions of memories and need semantic retrieval, of course you may need more sophisticated technology.
Lean AI Memory is aimed at a different problem.
A project has a relatively small amount of important context:

• decisions
• conventions
• unfinished work
• discoveries
• assumptions
• project history

For that kind of memory, maybe a Markdown file is enough.
Maybe it isn't.
That's exactly what I want people to try.

AI memory should not become a black box

One thing I care about is human control.
If an AI remembers something about my project, I should be able to see it.
If it is wrong, I should be able to change it.
If it is no longer relevant, I should be able to remove it.
If I want to know why something is there, Git history should help me understand it.
This gives a very simple relationship:

AI can write memory ⇆ Human can inspect memory ⇆ Human can change memory

The AI is not the owner of the memory.
The project is.

It doesn't have to be only for coding

I initially thought about AI coding agents.
But the more I think about the idea, the less important coding becomes.
The same concept could potentially work for:

Documentation
Remember:

• terminology
• writing conventions
• decisions
• unfinished sections

Research
Remember:

• hypotheses
• evidence
• rejected assumptions
• open questions

Business workflows
Remember:

• process rules
• decisions
• exceptions
• pending work

Team projects
Remember:

• shared decisions
• conventions
• responsibilities
• unresolved issues

Personal AI
Remember:

• preferences
• ongoing goals
• important context
• previous decisions

I don't know what all of these users need.
And I don't want to guess.
That's why the rules are open.

The interesting part may actually be the rules

The Markdown format is intentionally boring.
The interesting question is:

What rules will people create?

For example, a software team might define:

When an architectural decision is made, record the decision, reason and rejected alternatives.

Another team might say:

Never store customer data in AI memory.

A documentation project might say:

Never change an established business term without recording the reason for the change.

A research project might say:

Never treat an assumption as a fact. Record the evidence behind important conclusions.

These are completely different rules.
And that's okay.
I don't want to build a system that knows all of them.
I want to provide a simple place where people can define them.

What Lean AI Memory is

In one sentence:

Lean AI Memory is a small, Git-native protocol for persistent AI memory using human-readable Markdown and user-defined natural-language rules.

The design principles are:

• Human-readable
• AI-readable
• Local-first
• Git-native
• Rule-driven
• AI-agnostic
• Simple
• Human-controlled

What it is not

It is not:

• a vector database
• a semantic search engine
• a knowledge graph
• an enterprise memory platform
• a replacement for every AI memory solution

And I don't want it to become one just because adding features is tempting.
The project should remain understandable.
If someone opens the repository, they should be able to understand the idea without reading a hundred pages of documentation.

Why did I open source it?

Because I don't know if I'm right.
That's probably the most honest reason.
I can sit here and explain why Markdown is better.
I can explain why Git is enough.
I can explain why natural-language rules are useful.
But none of that proves the idea.
The only interesting test is:
Does somebody else find it useful?
Maybe someone will use it.
Maybe someone will tell me that the idea is wrong.
Maybe someone will create a rule set I never thought about.
Maybe someone will build an integration.
Maybe nobody will care.
All of those outcomes are useful information.
So I decided to open source it.
You can find the project here:
Lean AI Memory on GitHub

A small experiment, not a finished solution

I don't consider Lean AI Memory finished.
Actually, I'm not even sure the underlying idea is correct yet.
That's part of the experiment.
I wanted to build something small enough that people can understand it, modify it and disagree with it.
Maybe AI memory does need databases.
Maybe semantic retrieval will eventually be necessary.
Maybe Markdown will become inconvenient at some scale.
That's fine.
Those are engineering questions.
The first question is simpler:

Can humans and AI share a memory without hiding that memory behind another complicated system?

That's what I'm trying to find out.

Final thought

I've spent a lot of time working on software in different areas.
One thing I have learned is that sometimes the difficult part isn't writing the code.
It is deciding what should actually be built.
With AI, this becomes even more interesting.
AI can generate code extremely quickly.
But it doesn't automatically know what matters to you.
It doesn't automatically know what should be remembered.
It doesn't automatically know which rules your project should follow.
Those things still need to come from somewhere.
So maybe the future of AI memory isn't only about making memory smarter.
Maybe it is also about making memory understandable.

Maybe AI memory doesn't need to be smarter.
Maybe it just needs to be understandable.

Links

• GitHub: Lean AI Memory
• License: MIT
• Format: Markdown
• History: Git
• Rules: Natural language

If you try it, I'd be genuinely interested in seeing what memory rules you come up with.