Cortex

About Cortex

Cortex is a project intelligence engine for AI coding agents.

The problem it targets is simple: agents forget too much. A fresh session can read files and run commands, but it usually does not carry forward the parts of software work that matter most: why a decision was made, what approach was rejected, what usually breaks, and which constraints are real versus accidental. Many existing memory tools are useful, but most of them preserve observations. Cortex is designed to preserve understanding.

What inspired it

The project started from a practical frustration: every new session felt like rehiring the same agent. Even when the repository had not changed, valuable context disappeared between resets, compactions, and new conversations.

That led to the core idea behind Cortex: instead of trying to remember everything, it should preserve the small amount of project knowledge that actually changes how future work gets done.

What Cortex does

Cortex organizes project knowledge into three layers:

• Working memory for the current task
• Atomic project insights such as decisions, patterns, discoveries, and landmines
• Distilled wisdom such as architecture, invariants, and major risks

It also revolves around four operations:

• Bootstrap from an existing codebase
• Capture useful insights during work
• Load relevant knowledge into new sessions
• Consolidate lower-level insights into higher-level wisdom

Everything is stored as plain Markdown. There is no database, no background service, and no separate infrastructure layer.

How we built it

We built Cortex as a lightweight plugin-based system that can sit alongside existing agent workflows instead of replacing them.

The work focused on three things:

1. Designing a knowledge model that stays small enough to load quickly but rich enough to be useful.
2. Building a Bootstrap flow that can learn from an existing repository rather than only from new sessions.
3. Repeatedly testing the system on a real external codebase to see whether it produced useful project intelligence or just more notes.

What we learned

The biggest lesson was that durable memory is not enough.

What matters is whether the system can separate:

• signal from noise
• understanding from raw observation
• stable project truth from stale or weakly grounded claims

We also learned that project history is more valuable than it first appears. Source code explains what exists now, but review and decision history often explain why it ended up that way.

Challenges we faced

The hardest challenge was trust.

If a system stores too much, it becomes noisy. If it stores the wrong things, it becomes dangerous. That pushed us to be conservative about what counts as worth keeping and to focus on project intelligence rather than generic memory.

Another challenge was compression. Deep project understanding is valuable, but it has to fit into a limited context budget. That forced us to distinguish between what should always be loaded and what should only be retrieved when a task genuinely needs it.

At its core, Cortex is trying to answer one question:

How do you make an AI coding agent behave less like a stateless tool and more like a teammate who has actually learned the project?

Built With

• codex
• knowledge-management
• local-first
• project-intelligence