---
title: "Turn your agents into experts"
canonical: https://workspace.socra.com/docs/cortex/guides/turn-agents-into-experts
---

# Turn your agents into experts

Start with one real task and the smallest knowledge graph it requires. As later work exposes durable knowledge, ask the agent to search the existing graph and update the relevant Modules and dependencies, then explain what changed and why.

This guide follows one repeatable loop:

**Model → Connect → Flash → Work → Review → Refine**

At the end, your agent will flash a target Module and receive the complete foundation-first context required to work in that domain.

## Before you start

You need:

- The [Socra CLI and Cortex namespace](/docs/cortex/reference/cli) installed.
- A configured coding agent or terminal that can run Cortex commands.
- One real task that depends on knowledge specific to your organization.
- [Permission to create Modules](/docs/cortex/administration/access-and-permissions) in your Account.

If Cortex is not connected to your coding agent, follow [Coding agents](/docs/cortex/integrations/coding-agents).

## Use this guide with an agent

Give your coding agent the [Markdown version of this page](https://workspace.socra.com/docs/cortex/guides/turn-agents-into-experts.md).

Then ask:

```text
Read this guide and help me model one domain in Cortex. Inspect existing Modules, update the relevant ones or create missing ones, and keep their dependencies consistent. Flash to verify and tell me what changed and why.
```

The engineer supplies the requirements and reasons. The agent maintains the graph as the work reveals useful knowledge and explains its changes so the engineer can correct them.

## Choose one expert outcome

Start with a task where a capable coding agent still needs knowledge that it cannot reliably recover from the repository.

For example, suppose the agent must add partial refunds to a billing service. The repository can show how the service works today, but it might not explain two organization-specific decisions:

- All monetary values use integer minor units.
- A refund must reference a settled charge, and cumulative refunds must not exceed the settled amount.

Define the observable outcome before creating a Module:

> When the agent works on refunds, it retrieves both decisions, verifies the current implementation, and produces a change that preserves them.

Do not begin by importing a repository, handbook, or architecture document. Begin with the smallest body of knowledge that changes how the agent should perform the task.

## Inspect the existing graph

Map the knowledge basin:

```bash
socra cortex map
```

Search for Modules that might already own the relevant knowledge:

```bash
socra cortex module search --query money
socra cortex module search --query refund
```

Read each relevant Module before creating a new one:

```bash
socra cortex module get MODULE_NAME
```

Replace `MODULE_NAME` with the Module name returned by the search.

Update an existing Module when it already owns the subject. Create a new Module only when the knowledge has no current owner.

## Model stable abstractions

Treat a Module like a cohesive programming abstraction. It should own one subject, change for one class of reason, and expose knowledge that other Modules can reuse.

For the refund example, use two Modules:

| Module    | Knowledge it owns                                               | Dependencies |
| --------- | --------------------------------------------------------------- | ------------ |
| `money`   | How the organization represents and interprets monetary values. | None         |
| `refunds` | The invariants that every refund workflow must preserve.        | `money`      |

`refunds` depends on `money` because the refund invariants cannot be applied correctly without understanding monetary representation. `money` does not depend on `refunds` because monetary representation is useful independently.

Together, these Modules form a small [semantic directed acyclic graph (SemDAG)](https://workspace.socra.com/blog/engineering/the-semdag): meaning is separated into reusable abstractions, and dependencies assemble those abstractions in comprehension order.

Do not make the graph mirror repository directories, package imports, teams, or documentation folders. A Cortex dependency means **required for comprehension**.

### Write durable knowledge

Good Module content states the current rule and the reason it exists:

```text
Store and transmit monetary values as integer minor units. Pair every value with its ISO 4217 currency code because the currency determines the minor-unit scale. Do not use floating-point values for money. This prevents rounding differences across services and clients.
```

```text
A refund references one settled charge. The cumulative amount refunded against a charge must not exceed its settled amount. Record each refund independently instead of rewriting the original charge. This preserves an auditable financial history and makes partial refunds composable.
```

Exclude implementation status, file paths, migration notes, incident history, and instructions that apply only to the current task. The agent must verify changing implementation details from the current system.

### Decide when to split

Create separate Modules when either condition is true:

- The knowledge can be understood or reused independently.
- The knowledge has a different owner or changes for a different reason.

Keep knowledge together when splitting it would force every consumer to retrieve both parts to understand either one.

## Create the graph

Save the Module content and dependencies, flash to verify, and tell the engineer what changed and why.

Create the foundation Module:

```bash
socra cortex module create --name money --content "Store and transmit monetary values as integer minor units. Pair every value with its ISO 4217 currency code because the currency determines the minor-unit scale. Do not use floating-point values for money. This prevents rounding differences across services and clients."
```

Create the dependent Module:

```bash
socra cortex module create --name refunds --deps money --content "A refund references one settled charge. The cumulative amount refunded against a charge must not exceed its settled amount. Record each refund independently instead of rewriting the original charge. This preserves an auditable financial history and makes partial refunds composable."
```

If either Module already exists, review its current content and use `socra cortex module update` to save the updated knowledge. The `--deps` option replaces the complete dependency list; include every direct dependency that must remain.

## Verify the assembled expertise

Inspect the map again:

```bash
socra cortex map
```

Confirm that `refunds` depends on `money` and that no reverse or unrelated edge exists.

Flash the target Module:

```bash
socra cortex flash refunds
```

Confirm that Cortex returns `money` before `refunds` and includes each Module once. The output should contain enough context to explain both monetary representation and refund behavior without requiring the agent to guess either rule.

## Apply the expertise to real work

Give the configured coding agent a bounded task:

```text
Flash refunds. Then inspect the current billing implementation and propose the smallest change that supports partial refunds. Apply the flashed decisions, but verify all current implementation details from the repository and tests before changing anything.
```

The agent should:

1. Flash `refunds` before making a decision.
2. Read both `money` and `refunds` from the assembled context.
3. Inspect the current implementation instead of treating the flash as runtime evidence.
4. Preserve the monetary and refund invariants in its proposed or completed work.

The loop has failed if the agent receives the knowledge but cannot identify when it applies, or if the graph omits knowledge required for the task.

## Refine the graph from evidence

Review the agent's work and classify each problem before changing Cortex:

- **Missing durable knowledge:** Add it to the narrowest Module that owns the subject.
- **Wrong abstraction:** Split or combine Modules so each has one cohesive responsibility.
- **Missing comprehension dependency:** Add the direct edge required to understand the target Module.
- **Incorrect current-state assumption:** Fix the work or verification process. Do not encode changing implementation state as durable knowledge.
- **Unrelated execution gap:** Create an Issue against the narrowest Module that owns the expected behavior.

Update the relevant Module, flash the target again, and repeat the same task or an equivalent test. Tell the engineer what changed and why.

The graph is useful when the agent reliably retrieves the smallest complete body of expertise required for the work. It is not complete merely because it contains many Modules.

## Next step

Learn [how Modules and dependencies shape the knowledge map](/docs/cortex/concepts/modules-and-map), or learn [how Issues coordinate work against the same graph](/docs/cortex/concepts/issues-and-coordination).