The re-explaining problem
You know the drill. You open a new chat with an AI assistant, paste in a chunk of code, and before you can ask anything useful you're typing: "This is a Node.js API. We use Prisma for the ORM. Auth is JWT, not sessions. Controllers go in /src/controllers, not at the route level." Every. Single. Time.
It doesn't matter how good the model is. If it doesn't know your project, the first few exchanges are just orientation. You're not getting help — you're writing documentation for a robot that's going to forget everything the moment you close the tab.
That's the problem lac agent's project memory is built to solve.
How it works
When you run lac agent in a project directory, it looks for a file called .lac-memory.json at the root. If it exists, the contents get loaded into the agent's context automatically before your first message. No flags, no extra commands. It's just there.
The file is plain JSON, so you can read it, edit it, and commit it to git like any other config. A typical one looks something like this:
{
"stack": "Node.js, Express, Prisma, PostgreSQL",
"auth": "JWT via Authorization header, no cookie sessions",
"structure": {
"controllers": "src/controllers",
"routes": "src/routes",
"middleware": "src/middleware"
},
"conventions": [
"Always use async/await, never raw .then chains",
"Errors go through the centralised errorHandler middleware",
"All DB queries belong in the controller, not the route"
],
"currentFocus": "Refactoring the user profile endpoints"
}That's it. Next time you open a session, the agent already knows all of this. You start at the actual problem, not at "here's my stack."
What to put in it
I've been using this for a few projects now and the things that matter most are the non-obvious stuff — the decisions that aren't visible in the code itself.
The stack is the easy part. Any model can figure out you're using Express after reading two files. What it can't figure out from the code is:
- Why you chose one pattern over another ("we moved off sessions after a token-sharing bug in staging")
- Which parts of the codebase are off-limits or fragile ("don't touch the legacy payment module, it's being replaced next sprint")
- Team conventions that aren't enforced by a linter ("all new endpoints need an integration test, not just unit tests")
- What you're actively working on right now
The currentFocus field is the one I update most often. When I finish a feature I change it to the next one. Thirty seconds of upkeep saves several minutes of context-setting every time I open a new session.
It updates itself too
Here's the part I didn't expect to rely on as much as I do. When lac agent makes a significant decision during a session — renames a module, introduces a new pattern, adds a dependency — it can write back to .lac-memory.json to record what it did and why.
So if you ask it to restructure how errors are handled and it proposes a new pattern, it'll note that in memory. Next session, the agent knows the error handling was refactored and won't suggest reverting back to the old approach. The context compounds over time instead of resetting.
This is actually what makes the difference between a session-by-session AI assistant and something that starts to feel like a collaborator that's been on the project for a while.
Committing it to git
I commit .lac-memory.json to the repo. Some people add it to .gitignore, which is fine if there's anything sensitive in there, but for most projects the file is just architecture notes and conventions — exactly the kind of thing you'd want a new team member to read anyway.
If you've got a CONTRIBUTING.md or an ADR folder, think of .lac-memory.json as the machine-readable version of the same thing. Humans read the docs, the agent reads the JSON.
Starting fresh on a new project
If there's no .lac-memory.json yet, lac agent creates one during the session as it learns about your project. After a few exchanges it'll have picked up your stack from the files it reads, and you can edit the file to clean it up and add the context it couldn't infer.
On a brand new project I usually write the initial memory file myself before the first session. Five minutes at the start saves a lot of drift over the course of a week.
A quick workflow tip
At the end of a session, before you close the terminal, ask the agent directly: "Update .lac-memory.json with anything important we covered today." It'll add any new decisions, patterns, or context to the file. Takes ten seconds and means your next session picks up exactly where this one left off.
You can install lac-cli with pip install lac-cli or grab the install script from lacai.io/lac-cli. Run lac agent from your project root and drop a .lac-memory.json there. That's the whole setup.