Give each kind of context one clear home
AI agents usually struggle with context for a simple reason: everything gets mixed into one long message. The current request, official documents, remembered preferences, and repeatable methods are different kinds of information. MagicAssist gives each one a separate home. That separation helps an agent find what matters and helps a person understand why the agent made a choice.
MagicAssist provides several context surfaces because different information has different jobs. The issue carries the current objective. Comments record the active conversation and decisions. Memory retains durable learned facts, episodes, and summaries. Knowledge Base stores source documents and retrieves relevant passages with citations. Skills package repeatable methods and supporting files. Using the right surface is more important than collecting everything in one place.
A useful context system answers three questions for every piece of information: What kind of authority does it have? Where does it apply? When should it be reviewed or replaced? If those answers are unclear, the agent may use the right sentence for the wrong task.
Use the issue for current direction
The issue is the closest context to the work. It should state the observable outcome, current constraints, relevant inputs, and acceptance evidence. If a team decision changes while work is underway, record the decision in a comment and update the issue when necessary. This makes the active instruction visible to the assignee and reviewer.
Issue context is intentionally local. “Do not change the application repository during this website task” belongs in the issue because it is a boundary for one piece of work. “All production deploys require a verified database backup” may deserve a maintained Skill or workspace fact because it should influence many tasks. “The customer contract defines a 30-day retention period” belongs in an authoritative source document, not only in a comment.
- Put the current objective and non-goals in the issue.
- Put decisions made during execution in comments.
- Link to sources instead of pasting fragments that can drift.
- Keep acceptance checks close to the task they prove.
- Do not turn issue history into permanent workspace policy by accident.
Use Memory for learned operating context
Memory is for information learned through work that should be recallable later. MagicAssist separates facts, episodes, and rolling summaries. A fact is a concise statement such as “this repository uses pnpm with a frozen lockfile in CI.” An episode is a short account of a past event and its resolution. A summary condenses a longer conversation so a future turn can recover the important thread without replaying every message.
Scope is the central design choice. A workspace fact should apply broadly. A project fact should not leak into unrelated projects. An agent memory can capture a role-specific preference. A runtime memory can record a stable local capability, such as an available browser or connected command-line tool. Issue and chat-session scopes are appropriate when information should remain near one thread of work.
| Memory | Useful scope | Why |
|---|---|---|
| The release repository uses a signed-tag process | Project | Relevant to releases for that project, not every workspace task |
| This runtime has the Composio CLI available | Runtime | Capability belongs to one execution environment |
| The team prefers evidence before completion claims | Workspace | Operating preference applies broadly |
| The last migration failed because a lock was held | Episode in project or issue scope | Past event may inform the next related attempt |
Memory should not become a secret store, a document archive, or an excuse to omit task instructions. Recall is relevance-based and budgeted. The current issue must still be understandable if a particular memory is not retrieved. Write durable facts in language that will remain interpretable, and review them when the underlying environment changes.
Use Knowledge Base for source truth
Knowledge Base is for documents whose wording and provenance matter: specifications, API contracts, product positioning, policy, research, customer-approved material, and reference guides. MagicAssist extracts text, divides it into chunks, embeds it, and retrieves relevant passages when an agent claims work. Each retrieved passage carries source metadata so the agent can cite where an answer came from.
This makes Knowledge Base different from Memory. If an agent needs to answer, “What does the approved API contract say about retry behavior?” it should consult the source document. If it needs to recall, “Last week we moved this project’s retry implementation to exponential backoff,” that is learned project context and may belong in Memory. One is authority; the other is experience.
Scope matters here too. Workspace Knowledge Base is appropriate for material that should be available across projects: a brand guide, company terminology, security policy, or shared operating handbook. Project Knowledge Base is appropriate for a particular product specification, client brief, architecture decision record, or delivery research. A task tied to a project can retrieve from both; an unrelated task should not receive project-specific material.
Use Skills for repeatable method
A Skill answers “how should this kind of work be done?” It can include a SKILL.md, scripts, templates, reference files, or configuration. The method may tell an agent when the Skill applies, what order to follow, which checks to run, and how to present the result. Skills are useful for deployment procedures, review methods, research workflows, migrations, content production, or any process the team wants to improve once and reuse.
Do not put a changing project objective in a Skill. Do not use a Skill as a general document dump. The Skill should remain understandable as a method even when the individual issue changes. If it needs an approved project specification, the method can instruct the agent to retrieve that source from Knowledge Base. If it depends on a stable workspace preference, Memory may supply that fact. The surfaces work together without becoming interchangeable.
Because Skills may contain scripts or executable instructions, review imported material before attaching it to an agent. Storage in a workspace does not prove that third-party instructions are safe. Test the Skill with the provider and runtime that will use it, and remember that updated Skill content affects new tasks rather than changing an execution already underway.
A placement test for any piece of context
When deciding where information belongs, run a short placement test. Begin with authority. Is this the current instruction, a source document, a learned fact, or a repeatable method? Then check scope. Should it affect this issue, one project, one agent, one runtime, or the whole workspace? Finally, check maintenance. Who updates it, and what event should cause a review?
- Current and task-specific? Put it in the issue or active comments.
- Authoritative source whose wording matters? Put the document in the appropriate Knowledge Base scope.
- Learned fact or past episode that should be recalled? Put it in Memory with the narrowest useful scope.
- Repeatable procedure with steps or supporting files? Turn it into a reviewed Skill.
- Temporary scratch material? Keep it with the task output; do not promote it merely because it exists.
The narrowest useful scope is usually safer. A runtime capability should not become a workspace-wide assumption. A customer-specific preference should not influence another project. A historical decision should not remain active after it is superseded. Explicit scope reduces accidental authority.
Worked example: a product launch brief
Suppose a team wants an agent to prepare weekly launch updates. The approved launch brief, positioning, timeline, and channel plan are source documents, so they belong in the project’s Knowledge Base. The issue for this week’s update states the audience, cutoff time, required sections, and acceptance checks. Comments capture a new decision to delay one announcement.
During earlier runs, the team learned that the executive summary should lead with risks and decisions rather than completed activity. That stable project preference can become a project-scoped Memory fact. The weekly reporting method—retrieve the current brief, collect issue changes since the cutoff, separate facts from open questions, produce the approved structure, and list missing sources—can become a Skill. An Autopilot may later create the weekly issue and assign it.
Each surface now has one job. If the launch date changes, update the source brief. If this week’s decision changes, update the issue or comment. If reviewers establish a durable preference, revise the Memory fact. If the reporting process improves, update the Skill. The next agent run receives focused context with a traceable route back to authority.
Maintain context through normal work
Context systems decay when maintenance is treated as a separate cleanup project. Use normal review as the feedback loop. When an agent cites an outdated source, update or retire the document. When reviewers repeatedly add the same correction, decide whether it is a task template, Memory fact, or Skill improvement. When a fact stops being true, edit or delete it. When a Skill’s instructions no longer match the toolchain, fix the method before assigning more work.
Durable context is not everything the team has ever written. It is the maintained material a future task can interpret with the right authority and scope.
The aim is not to make every agent omniscient. It is to help each task receive the smallest complete context set: current direction from the issue, relevant sources from Knowledge Base, useful learned context from Memory, and a repeatable method from Skills when one applies. That is how context becomes an operating asset instead of a longer prompt.