lac agent's Project Memory: What .lac-memory.json Actually Does

The Re-Explaining Problem

Before I started using lac-cli, every coding session with an AI assistant started the same way: paste in the file structure, explain the stack, remind it which database ORM we're using, clarify that yes, we do handle auth in middleware and not in the controllers. Every. Single. Time.

It wasn't a huge deal per prompt, but it adds up. And worse, the re-explaining made it feel like the assistant was a temp worker who showed up fresh each morning with no idea what the project was.

lac agent solves this with a file called .lac-memory.json. It lives in your project root, it's plain JSON, and once it exists the agent reads it automatically at the start of every session. You write it once (or let the agent build it up over time), and the context just... sticks.

What the File Actually Contains

When you run lac agent in a project for the first time and the agent makes meaningful discoveries — your stack, your folder conventions, key files it touched — it writes those findings into .lac-memory.json. Over sessions it keeps updating the file as the project evolves.

A typical entry looks something like this:

{
  "project": "storefront-api",
  "stack": ["Node.js", "Express", "PostgreSQL", "Prisma"],
  "entry_point": "src/index.js",
  "auth": "JWT middleware in src/middleware/auth.js",
  "conventions": {
    "routes": "src/routes/*.js",
    "controllers": "src/controllers/*.js",
    "models": "Prisma schema at prisma/schema.prisma"
  },
  "tasks": [
    { "id": 1, "description": "Add pagination to /products", "status": "done" },
    { "id": 2, "description": "Implement soft deletes on orders", "status": "in_progress" }
  ],
  "notes": "Avoid using raw SQL — always go through Prisma client."
}

That's a simplified version, but the structure is the point. The agent loads this at session start and immediately knows the project's shape without you having to say a word.

The Tasks Array Is More Useful Than It Looks

I glossed over this when I first set up lac agent. The tasks array inside .lac-memory.json is the agent's built-in task tracker. When you ask it to do something — "add rate limiting to the auth routes" — it logs that as a task with a status of in_progress. When it's done, it marks it done.

This means if you quit mid-session and come back tomorrow, you can just run lac agent, and it'll pick up where it left off. It knows which tasks are still open. You don't need to remember "oh right, I was in the middle of the rate limiting thing."

You can also manually add tasks to the file before a session. I sometimes write a quick list of what I want to work on, push it into the tasks array the night before, and the agent walks through them in order the next morning.

Writing a Good Memory File by Hand

The agent builds the file automatically, but it doesn't always capture the nuance you actually care about. I've found it worth spending ten minutes writing a solid baseline memory file when starting a new project — think of it as onboarding documentation, but for your AI assistant instead of a new developer.

A few things worth putting in the notes field specifically:

• Patterns you don't want the agent to use. ("Don't add try/catch in route handlers — errors bubble up to the global error middleware.")
• Third-party services the project talks to and how. ("Stripe webhooks are verified in src/webhooks/stripe.js, signature check before any processing.")
• Where the environment config lives and which variables matter. ("DB_URL, JWT_SECRET, and STRIPE_WEBHOOK_SECRET must be set. See .env.example.")
• Anything that's non-obvious about the deployment target. ("Deployed on Railway — no filesystem writes, everything goes to S3.")

The agent treats the notes field as high-priority context. Anything you put there will actively shape its suggestions, not just sit in the file as metadata.

PlanMode + Memory = A Smarter Starting Point

PlanMode is another lac agent feature worth using alongside this. When you start a session with lac agent --plan, the agent reads your memory file and then lays out a step-by-step plan for what it's about to do before touching a single file. You review the plan, tweak it if something looks off, then approve it.

With a well-written memory file, the plan it generates is usually about 80% right on the first try. Without it, PlanMode still works but it's making guesses about your project structure that you'll need to correct.

The combination looks like this in practice:

1. Project memory gives the agent architectural context upfront.
2. PlanMode turns that context into a concrete action plan you can review.
3. You approve (or tweak) the plan, and the agent executes with undo/redo available at every step.

That last point matters — lac agent gives you a diff preview before committing any write, and /undo reverts changes if something goes sideways. So even when the agent does something unexpected, you're never stuck.

Keeping the File Healthy

One thing I do is commit .lac-memory.json to the repo. If you're working on a team and someone else also uses lac agent, they get the full project context immediately when they clone and run lac agent in the directory. It's like committing a living README that the agent actually reads.

If the file gets stale — the stack changed, you refactored the folder structure — just edit it directly. It's plain JSON, takes thirty seconds. Or ask the agent itself: "Update the memory file to reflect the new routes structure" and it'll rewrite the relevant sections and mark them updated.

Quick Start

If you haven't tried lac agent yet, install it with:

pip install lac-cli

Then run it inside any project directory:

lac agent

On first run it'll scan the project and start building .lac-memory.json automatically. If you want to seed it manually before that, just create the file in your project root with at minimum a project name and stack array — the agent will fill in the rest as it works.

For a more deliberate first session, use:

lac agent --plan

Give it your first task and watch how different it feels when the agent already understands the project before you've typed a single instruction.