Project Knowledge - Modelcode

Project Knowledge is where all structured project context lives in the product — the Project Spec, Project Setup (lifecycle scripts, environment variables, dependencies, Dockerfile), milestones, wikis, and rules — together with Knowledge chat for conversing with the Morph Platform. You open it from the Roadmap: under Modernization, click Project Knowledge. During onboarding the Morph Platform opens this drawer for you twice: first to review and approve the Project Spec, and then — at the High validation level — to go through Project Setup, discovering and validating the application’s lifecycle alongside the agent. Throughout the migration, agents read from and write to the same underlying knowledge; this UI is how you inspect and steer it.

What Project Knowledge Is

Think of Project Knowledge as structured context for Morph agents, surfaced in a full-height drawer on the Roadmap. Every time an agent works on a task, the agent reads this knowledge to understand your project’s architecture, conventions, how the application actually runs, and decisions already made. When an agent learns something new during execution — a pattern the agent discovered, an architectural decision, a fix to a startup script — the agent writes that back (often as wiki pages, rules, or lifecycle updates). This is how agents pass knowledge to each other. Onboarding establishes how the app installs, builds, and runs (for projects on High validation). Milestone 1 might establish a database access pattern. Milestone 5, handled by a different agent, reads both from the same project knowledge and follows them. The result is consistent code across your migration — and a configuration the agent can actually run — even when different agents handle different parts.

What’s Inside

Project Knowledge is organized in a tree:

Type	What It Holds	How It’s Used
Project Setup	Lifecycle for Origin and Target (scripts, environment variables, lifecycle document), Acceptance Criteria, plus either Dependencies (self-hosted) or Dockerfile (cloud)	Agents use the lifecycle to run, validate, and functionally test the application; acceptance criteria define quality gates
Project Spec	Goals, scope, and approach for the migration	Agents reference the Project Spec to stay aligned with the overall direction
Milestones	Detailed descriptions and scope for each migration step	Agents use milestone content to understand what each step requires
Wiki	Architecture docs, design decisions, patterns discovered during migration	Agents read wikis to understand project context and conventions
Rules	Coding standards, library preferences, explicit constraints — grouped as Published, Draft, or Archived	Agents follow published rules as hard requirements in every milestone

How Agents Use It

When an agent starts working on a milestone:

It reads the Project Spec to understand the migration’s overall goals
It reads the Project Setup to know how to install, build, run, and health-check the app
It reads all rules to know which standards to follow
It reads relevant wiki pages to understand architecture and patterns
It reads the milestone description to know what to build

After execution, the agent writes back anything it learned — new patterns, architectural decisions, integration notes, and any lifecycle fixes it needed to make the app run — as wiki pages or as updates to the lifecycle configuration. That keeps project knowledge growing and more accurate over the course of the migration.

Opening Project Knowledge

During onboarding — Project Spec: When your Project Spec finishes generating, the drawer opens with Project Spec selected so you can review and approve it. During onboarding — Project Setup: After you approve the spec and pick the High validation level, the Project Setup stage on the Roadmap opens the drawer again with Knowledge chat seeded to start setup — the agent walks you through discovering and validating how your application installs, builds, runs, and is health-checked. See Project Setup (Onboarding) below. Any time after that: Go to the project’s Roadmap. In the left Modernization column, click Project Knowledge to open the drawer. You can also open it from flows that link knowledge (for example, opening a rule, milestone, or lifecycle script in context).

Project Setup (Onboarding)

Project Setup is the branch of the Project Knowledge tree that holds everything the Morph Platform needs to actually run your application. It’s also where the Project Setup onboarding stage happens — the agent collaborates with you in Knowledge chat to fill this branch in, then validates it end to end.

Project Setup runs only at the High validation level, after the Project Spec is approved. At Low and Mid, the Morph Platform never builds or runs the origin application, so there is no origin lifecycle to set up. See Validation Level.

The branch is organized by side of the migration, mirroring the rest of project knowledge:

Origin — How the source application builds and runs. Discovered together with you during onboarding and used as the behavioral baseline for functional testing.
Target — How the destination application builds and runs. Discovered automatically during the foundation milestone (Milestone 1) so the target side is ready before migration code starts landing.
Dependencies and Dockerfile — Project-wide artifacts the agent builds during onboarding and keeps in sync as the project evolves.

Each origin/target entry contains three sub-items you can select in the tree:

Sub-item	What it is
Scripts	Ordered shell scripts — typically `install`, `build`, `run`, `healthcheck`, and `test` — that bring the app to a healthy, running state
Environment Variables	Variables and secrets the app needs at build or runtime, discovered from the codebase or set explicitly. Secrets are encrypted at rest
Lifecycle Document	A markdown overview describing the application’s architecture, the execution order of scripts, and how each phase fits together

How Project Setup flows through this drawer

The Project Setup stage on the Roadmap routes you into the Project Knowledge drawer with the chat focused on lifecycle discovery. Until the agent has discovered something to show, the drawer is chat only — the tree and content pane appear once the configuration exists. From there:

The agent inventories your repository — framework, install/build/run commands, healthcheck signals, env vars and secrets, external service dependencies — and reports back what it found before writing anything.
It proposes the lifecycle phases (install / build / run / healthcheck / test, plus optional steps like migrate or per-service splits in multi-environment projects) and confirms them with you.
It registers the scripts and environment variables, asking you for any values it can’t infer (service URLs, tenant-specific config). Credentials are requested with a Provide Secret card that encrypts the value immediately — never type a secret into the chat box.
It executes the lifecycle end-to-end to validate it actually works. On failure, it surfaces the failing phase, the last lines of output, and a proposed fix before retrying.
Once validation passes, the lifecycle is marked Validated and onboarding continues to Generate Roadmap. If the agent can’t get it fully healthy, it asks you to confirm saving the configuration as Draft — Needs Review so you can correct it. It is also Draft when a test or check couldn’t run because something it needs is missing, such as a secret or a service it can’t reach; the validation output names what is missing. Provide it, then re-validate.

You can see this happen live in the drawer: the tree on the left shows the Project Setup branch filling in as the agent works, and the chat on the right is where you answer questions and approve choices.

Lifecycle validation statuses

A status bar at the top of the Project Setup panel tells you whether your lifecycle is ready — and, when it isn’t, what to do next. The statuses and what each one asks of you are covered in Lifecycle Setup.

Project Setup tree and content panel in the Project Knowledge drawer

Editing the lifecycle later

Scripts and environment variables stay editable in the panel — use Add Script, Add Variable, and Save Changes. The lifecycle document, Dockerfile, and Dependencies are displayed read-only; the last two carry the hint “Read-only — ask the chat to update this.” Change any of them by asking the chat. Running validation always goes through the chat. Re-validate in the toolbar hands the run to the agent, so you can watch it work and answer questions mid-run. Ask Knowledge chat whenever you’d rather have the agent work the change out itself. Typical asks:

The run script should bind to port 8080, not 3000.
Re-validate after the change.

Add a `migrate` script that runs `alembic upgrade head` before `run`.

DATABASE_URL should point at a local Postgres on localhost:5432
for validation. Save it as a regular env var, not a secret.

For a full walkthrough of the Project Setup chat flow, the panel sections, and validation states, see Lifecycle Setup.

Knowledge Chat

Knowledge chat is the chat panel on the right side of the Project Knowledge drawer. It is your primary way to interact with the Morph Platform when working with project knowledge — onboarding, Project Spec review, lifecycle changes, wiki and rule management all happen here.

Sessions

Knowledge chat supports multiple sessions. Use the session picker at the top of the chat panel to switch between existing conversations or start a New chat. Each session keeps its own history, so you can have separate threads for different topics (lifecycle tuning, architecture decisions, rule changes) without losing context. Sessions may show which daemon they are running on (displayed as ”· on <daemon>” next to the session name).

Chat history and retention

Chat conversations are saved by default so you can come back to a session and see what was discussed and decided. A saved conversation opens straight away, even if the chat is paused. A paused chat shows a Paused badge; send a message to continue it. If the chat ran on a self-hosted machine that is now offline, you can still read the conversation, and you can continue once that machine is back online. If your organization would rather conversations were not retained on our servers, contact support@modelcode.ai. We can turn off chat history for a project, or permanently delete the history already saved. Customers can’t turn this off themselves. Two things to weigh before asking us to turn it off:

Conversations cannot be recovered if the workspace is lost.
Workspaces are recycled after 7 days of inactivity, so without persistence, history from an idle project goes with it.

Preparing and warmup

When you open Knowledge chat, the Morph Platform may need a moment to prepare a sandbox on the daemon — allocating a workspace, cloning the repository, installing dependencies, and indexing the codebase. This warmup happens automatically and you can see its progress in the chat panel. After the first warmup, subsequent opens are faster because the environment is already cached.

Session locking

Only one user can actively control a Knowledge chat session at a time. If a teammate already has an active session, you see a message naming the user who holds the lock. The session unlocks when that user finishes or their session times out after inactivity. This prevents the agent from receiving conflicting instructions from multiple users at the same time. If you need to work in Knowledge chat while a teammate holds the lock, coordinate with them directly.

Exclusive access and moving workers

Sometimes a Knowledge chat session needs exclusive access to the application process on the daemon (for example, to run lifecycle commands). If another job is already using that access on the same worker, your chat is parked — it waits for the other job to finish. If the pool has another available daemon, the Morph Platform offers a Move to a free worker option so your chat can continue on a different daemon without waiting.

Pool capacity

Knowledge chat is exempt from the daemon pool execution capacity gate. You can start a Knowledge chat session even when all workers in the pool are busy with milestone or ad-hoc executions.

Review work goes to Code Review chat

Knowledge chat plans and edits project knowledge, including the plans of milestones that haven’t started. It doesn’t do review work on a milestone: pull request comments, reviewer feedback, automated review findings, or changing and pushing code on a milestone’s branch. That work belongs in the milestone’s Code Review chat, which has the pull request context, the review findings, and push access to the branch. If you ask Knowledge chat for review work, it says the work belongs in that milestone’s review chat and points you there:

Milestone waiting for review — When the milestone has its pull request open, the reply ends with an Open review chat for milestone N card. Click Open to go straight to the review chat.
Milestone already merged — Its review chat is read-only, so Knowledge chat offers to create an adhoc milestone for the follow-up work instead.

Knowledge chat reply explaining that a pull request comment is handled in the milestone's review chat, followed by an Open review chat for milestone 1 card with an Open button

Adding Your Own Knowledge

You can add context at any time. This is useful when you have documentation, design decisions, or standards that the Morph Platform should know about from the start.

When you add content, it isn’t stored as a single blob. the Morph Platform breaks it down into structured wiki pages and rules, optimized for how agents consume it. A long design doc becomes focused, referenceable entries agents can query efficiently.

Using the Chat

Use the Knowledge chat panel to talk to the Morph Platform and create, update, or reorganize knowledge. To add documentation:

Open Project Knowledge from the Roadmap (Modernization → Project Knowledge)
Open the chat panel if it is hidden
Describe what you want to add

For example:

We use the repository pattern for all database access.
Each entity has its own repository class that extends BaseRepository.
Repositories handle all SQL queries — services never write raw SQL.
Here's an example from our codebase:

class UserRepository(BaseRepository[User]):
    async def find_by_email(self, email: str) -> User | None:
        return await self.find_one({"email": email})

the Morph Platform takes this and creates the appropriate wiki pages and rules so that every agent follows this pattern.

Dragging in Files

You can drag text files directly onto the chat panel to import existing documentation. the Morph Platform reads the file, extracts the relevant knowledge, and creates wiki pages and rules from the imported content. Supported formats include .md, .mdx, .txt, .yaml, .json, .py, .ts, .js, and other common text-based formats (up to 1 MB per file). Example use cases:

Drag your team’s CONTRIBUTING.md to import coding standards
Drop an architecture decision record (ADR) to capture design choices
Import a styleguide.md to encode formatting preferences

From a URL or Repo Path

In the chat, you can also reference external sources:

Please read the coding standards from our wiki at
https://internal-wiki.example.com/coding-standards
and create rules from them.

Or point to a file in your repository:

Read the patterns in src/shared/base-repository.ts
and create a wiki page documenting the repository pattern we use.

Editing Wiki Pages

Wiki pages capture architecture, patterns, and project-specific context. Update them through the chat. Right-click any item in the tree (wiki, rule, milestone, Project Spec, etc.) and select Add to context to attach it to the chat. You can also select text in the content panel and use the same Add to context action. Then describe the change you want:

Add a section about connection pooling.
We use a max of 20 connections per service instance.

Create a new wiki page about our error handling strategy.
All domain errors should extend AppError. HTTP errors are mapped
in the error middleware, not in individual handlers.

On Project Spec, milestones, wikis, and rules you can also leave artifact comments on selected text — useful for team review before asking chat to apply changes.

When to Add Wiki Pages

Add wiki pages when you have knowledge that applies broadly but isn’t a hard rule:

Architecture decisions — “We chose event sourcing for the order service because…”
Integration notes — “The payment gateway expects ISO 8601 dates with timezone”
Migration context — “The legacy UserManager class maps to three separate services in the new architecture”
Patterns — “All API responses follow the envelope pattern: { data, meta, errors }”

Editing Rules

Rules are hard constraints that agents follow in every milestone. Unlike wiki pages (which provide context), rules are treated as requirements. Create and update rules through chat:

Create a rule: all Python files must use absolute imports.
No relative imports allowed except in __init__.py files.

Manage rules in the UI: select a rule in the tree to edit its content, change status (Draft → Published → Archived), or delete it. New rules start as Draft until you publish them — only Published rules apply to agent execution. To update an existing rule via chat, right-click it (or select text) and Add to context, then describe the change:

Update this rule to also require that every new endpoint
has at least one integration test.

Rules vs. Wiki Pages

	Rules	Wiki Pages
Agent behavior	Treated as requirements — agents must follow them	Treated as context — agents use them to inform decisions
Scope	Apply to every milestone (when published)	Referenced when relevant
Best for	Coding standards, library mandates, naming conventions	Architecture docs, design decisions, integration notes
Example	”Use pytest for all tests. No unittest."	"The authentication service uses JWT with RS256 signing.”

Use rules when you want to enforce something. Use wiki pages when you want to inform agents.

Editing Milestones

You can review milestone descriptions in Project Knowledge. To adjust scope, add requirements, or change descriptions, use Editing Milestones from the milestone review flow. You can also ask the Morph Platform to restructure milestones through chat. For example, to merge two milestones:

Merge Milestone 3 ("Migrate user authentication") and
Milestone 4 ("Migrate session management") into a single milestone.
They're tightly coupled and should be done together.

Locked Milestones

Milestone plans in Project Knowledge are view-only once execution has started. A milestone is locked as soon as a run for it is queued, and stays locked while its status is anything other than Not Started (in progress, pending review, failed, blocked or merged). To change the result of a milestone that has started, review its pull request and ask the milestone’s Code Review chat for fixes, or create an adhoc milestone for larger follow-up work.

For small, recurring adjustments across milestones, add a Rule instead of editing each milestone individually. Published rules apply to all milestones automatically.

Updating the Project Spec

The Project Spec is the top-level document that defines your migration’s goals, scope, and approach. Ask the Morph Platform in chat to refine the migration direction; substantial changes may also go through your Project Spec approval flow (see Project Spec). Changes to the Project Spec can affect how agents approach future milestones, so be deliberate about what you request.

Adding a Repository Later

Sometimes a migration needs a repository you didn’t select when you created the project — a shared library the code imports, a service the backend calls, or another application to migrate. Add origin repo attaches that repository to the project as another source (“origin”) repository and opens a Knowledge chat that plans the project changes it needs.

Adding the Repository

Adding a repository closes every chat open on the project, including Code Review and help chats. Each chat ends and its workspace is removed: a reply still in progress stops, and changes the chat made but hadn’t saved are discarded. Finish or save anything you need in those chats first.

Open Project Knowledge from the Roadmap and select Project Spec in the tree.
In the Repo map, under Before migration, click Add origin repo.
Under Repository, pick the repository. Repositories already in the project and empty repositories can’t be picked.
Under How will the project use it?, choose a role:
- Read only — Used as a reference. Never changed.
- Edit in place — Changed in place, on the project’s feature branch.
- Migrated to a new repo — Read as the source. The modernized code goes to a new repository. Enter the New repository name, and under Create it in pick where to create it. In the Repo map, this repository then shows as Read only and the new one as Full migration.
In Why are you adding this repo?, explain what the project needs it for — for example, “the backend calls this service’s API”. The planning chat starts from this.
Click Add repository.
If any chats are open on the project, the Morph Platform lists them. Click Close chats & add repository to continue.

Add origin repository dialog with a repository picked, Migrated to a new repo selected, a new repository name, where to create it, and the reason for adding it

For Migrated to a new repo, when the new repository is created depends on the Project Spec. If the spec is already approved, the Morph Platform creates the repository when you add it. If the spec is still a draft, the repository is created when you approve the spec, like any other new repository in the Repo map.

The Planning Chat

After the repository is added, a new Knowledge chat opens to plan the changes for it. The chat studies the repository and proposes:

Wiki changes.
Project Spec changes. If the spec is already approved, only its text changes; the Repo map stays as it is.
Build-and-run changes, on projects with origin lifecycle scripts at the High validation level. The chat works out whether the app needs the repository to build or run, and proposes the build-and-run and Dockerfile changes that follow.
Roadmap changes, once milestones exist: edits to milestones that haven’t started, and new milestones added after the last one. Milestones that have already started are not changed.

The chat applies nothing until you agree. If you ask for something different, it proposes again. Once you confirm, it applies the changes and finishes adding the repository, and milestones can start again. An added repository stays attached to the project. If you decide you don’t need it after all, tell the chat and it leaves the repository out of the plan.

While the Repository Is Being Added

Until the repository has been added, milestone work on the project is on hold:

Milestones can’t be started or retried, and upstream syncs, rebases, and adhoc runs can’t start either. On the Roadmap, a milestone’s Start button is replaced by Open the chat, which takes you back to the planning chat.
The Project Spec can’t be approved.
You can’t add another repository.

If the planning chat ends before it has applied the changes, a banner appears above the Repo map: Adding repository name is in progress. It has two actions:

Open the chat — Opens a new planning chat that continues from what the earlier chat already saved.
Mark as done — Finishes adding the repository without the chat and unblocks milestones right away. Use it only if the project is already updated for the repository. Any wiki, Project Spec, build-and-run, or roadmap change the chat hasn’t applied yet is dropped, and milestones that run afterward won’t account for the repository. Confirm with Mark as done anyway.

Banner reading Adding repository task-manager-api is in progress, with Open the chat and Mark as done

When You Can’t Add a Repository

Add origin repo is disabled, with the reason in its tooltip, while:

A run on the project is in progress, paused, or waiting to retry — for example a milestone run. Let it finish, or resume or cancel it, then add the repository. Open chats don’t block adding a repository.
Another repository is being added.

Add origin repo doesn’t appear at all:

For users without permission to edit the project and its Project Spec
On trial projects created from a public repository
On sample projects
Once the Final Code Delivery pull request is open

If you can’t edit the project, ask someone who can to add the repository.

Suggested Repositories

When the Morph Platform generates the Project Spec, it looks for your organization’s private repositories that the code depends on. If it finds any that aren’t attached to the project, the Project Spec lists them above the Repo map under Repositories the code references that aren’t attached, with where the code references each one. Click Add origin repo on a row to open the same dialog, with the reason already filled in.

Viewing Changes

When the Morph Platform modifies knowledge during an agent execution (for example, an agent discovers a pattern and writes a wiki page), you can see exactly what changed. Click Show changes (the diff icon) in the Project Knowledge toolbar to toggle an inline diff view:

Green highlights show added content
Red highlights with strikethrough show removed content
A summary shows the total lines added and removed
Modified items are marked with a status dot in the tree navigation

This makes it easy to review what agents learned and wrote back during execution. The button is disabled when there are no pending changes to show.

How Knowledge Stays in Sync

Project knowledge stays aligned with running work as agents read and write it, and as you add or update context through the chat. When you ask for changes while an agent is running, the Morph Platform incorporates them so agents can pick up new rules and wiki context in subsequent steps. Knowledge chat also keeps documents consistent with each other within a conversation:

Project Spec or milestone changes — When a change to the Project Spec or a milestone plan contradicts a wiki page or a rule, the chat includes a fix for that statement in the same proposal. It edits the wiki page or rule in place. If a rule no longer applies at all after the change, the chat proposes archiving it. Pages that just don’t mention the change, or that describe the original code as it is today, are left alone.
Wiki or rule changes — When you ask for a wiki page or rule that contradicts the Project Spec or a milestone plan, the chat points out the conflict and asks which side should change. The Project Spec is the source of truth, so the chat never changes it to match a wiki page or rule without your confirmation.

Examples

Setting Up a New Project’s Knowledge

When you start a migration, front-load project knowledge with what you know:

Our project follows clean architecture. The layers are:
- Domain (entities, value objects, repository interfaces)
- Application (use cases, DTOs, application services)
- Infrastructure (database repos, external API clients, message handlers)
- Presentation (controllers, middleware, request/response models)

Dependencies point inward. Infrastructure depends on Domain,
never the reverse. Use dependency injection everywhere.

the Morph Platform creates wiki pages for the architecture and rules for the dependency direction constraint.

Correcting Agent Behavior

After reviewing a PR, you notice agents are using console.log for debugging:

Create a rule: never use console.log in production code.
Use the logger service from src/shared/logger.ts for all logging.
Debug logs should use logger.debug(), errors should use logger.error()
with the full error object.

All future milestones follow this rule once you publish it.

Importing Team Standards

Your team has a docs/coding-standards.md in the repo:

Drag the file onto the Knowledge chat panel
the Morph Platform reads it and creates wiki pages and draft rules from the content
Review the created entries in the tree navigation
Publish rules you want enforced, and ask the chat to adjust any entries that need refinement

Project Knowledge with the milestone spec open, the knowledge tree on the left, and Knowledge chat on the right

Adding Context Mid-Migration

At Milestone 4, you realize agents don’t know about a critical integration:

The user service calls the billing service over gRPC.
The proto files are in shared/proto/billing.proto.
When migrating user-related code, preserve all billing
service calls and use the generated Python client from
shared/generated/billing_pb2_grpc.py.

Milestones 5 onwards now have this context.

Best Practices

Let the Chat Do the Structuring

Don’t worry about formatting your input perfectly. Describe what you want in natural language and the Morph Platform structures it into the right wiki pages and rules. A rough paragraph of context works better than trying to manually create the “right” wiki page.

Review Agent-Created Knowledge

After each milestone, open Project Knowledge and check for new wiki entries and draft rules. Agents write back what they learned. If something is inaccurate, ask the chat to correct or remove it before the next milestone picks it up.

Use Rules for Enforcement, Wikis for Context

If you find yourself writing a wiki page that says “always do X” — that’s a rule. Move it there so agents treat it as a hard requirement, not optional context.

Lifecycle Setup

Reference for lifecycle scripts, env vars, validation status, and re-validation

Validation Level

How High vs Low/Medium affects Project Setup onboarding

Organizational Knowledge

Import organizational knowledge from existing projects

Reviewing the Project Spec

Approve the Project Spec using Project Knowledge and chat

Creating Rules

Deep dive into writing effective rules with examples

Editing Milestones

How to adjust milestone scope and descriptions

Core Concepts

Morph terminology and mental model

What Project Knowledge Is

What’s Inside

How Agents Use It

Opening Project Knowledge

Project Setup (Onboarding)

How Project Setup flows through this drawer

Lifecycle validation statuses

Editing the lifecycle later

Knowledge Chat

Sessions

Chat history and retention

Preparing and warmup

Session locking

Exclusive access and moving workers

Pool capacity

Review work goes to Code Review chat

Adding Your Own Knowledge

Using the Chat

Dragging in Files

From a URL or Repo Path

Editing Wiki Pages

When to Add Wiki Pages

Editing Rules

Rules vs. Wiki Pages

Editing Milestones

Locked Milestones

Updating the Project Spec

Adding a Repository Later

Adding the Repository

The Planning Chat

While the Repository Is Being Added

When You Can’t Add a Repository

Suggested Repositories

Viewing Changes

How Knowledge Stays in Sync

Examples

Setting Up a New Project’s Knowledge

Correcting Agent Behavior

Importing Team Standards

Adding Context Mid-Migration

Best Practices

Let the Chat Do the Structuring

Review Agent-Created Knowledge

Use Rules for Enforcement, Wikis for Context

Related Docs

Lifecycle Setup

Validation Level

Organizational Knowledge

Reviewing the Project Spec

Creating Rules

Editing Milestones

Core Concepts