DEV Community: Agent Project Context

Global Context Belongs Outside APC

Manuel Bruña — Fri, 26 Jun 2026 12:03:13 +0000

Global Context Belongs Outside APC

APC is the portable context layer. APX is the local runtime and tooling layer that makes APC useful every day. The easiest way to keep that split healthy is to draw one hard line: if something should survive a fresh clone, it belongs in APC. If it depends on one user, one workstation, or one running process, it should stay outside APC.

That sounds obvious until a project starts growing. Then the temptation appears: one more setting, one more token, one more local path, one more personal preference. If you are not strict, project context slowly turns into a dump of everything the machine knows. At that point the repo stops being portable and starts being fragile.

What belongs in APC

APC is for project-owned meaning. In the APC docs and README, that means the shared contract a repository can carry around with it.

Good APC content looks like this:

project identity
agent roles
reusable skills
curated project memory
project-level MCP hints
repo-wide instructions in AGENTS.md

These are facts a teammate, a new runtime, or a second machine should be able to read right after checkout. They help another tool understand the project without needing any hidden local state.

What does not belong in APC

Global context is different. It belongs to a user account, a workstation, or a runtime installation.

Examples:

API keys
editor preferences
local aliases
machine-specific tool paths
private runtime memory
caches
session transcripts
message logs
one-off debug notes

APX keeps this kind of state local on purpose. Its README is explicit: runtime state lives under ~/.apx/, not in the repository. That split is not cosmetic. It is what keeps the project shareable.

Why the split matters

If global and project context mix, three problems show up fast.

First, portability breaks. A repo that silently depends on one person's local config is hard to clone and harder to trust.

Second, review gets noisy. A pull request should show project decisions, not somebody's workstation baggage.

Third, secrets leak more easily. The moment a repo starts storing machine-local details, people forget which file is safe to commit and which one is not.

APC avoids all three by keeping the portable layer small and readable.

A simple test

Before adding a file or setting, ask one question:

Would another contributor cloning this repo need it immediately?

If yes, put it in APC.
If no, keep it outside APC.

A few concrete examples help:

A reviewer agent that every clone should know about? APC.
Your personal API key? Not APC.
A project decision about how to handle permissions? APC.
Your local browser profile path? Not APC.
A shared MCP hint that tells tools which server matters for this repo? APC.
A cache of the last run? Not APC.

That rule is boring, but it works.

What APX does with the boundary

APX is the runtime that reads APC and makes it operational. It registers projects, runs agents, reads memory, tails messages, and bridges to runtimes and MCPs.

That is why APX can keep local state without polluting the repo. A project can stay clean in git while APX still remembers what happened on this machine.

A tiny workflow shows the split:

apx init
apx memory reviewer
apx messages tail

apx init makes the project visible to the runtime. apx memory shows durable, curated facts. apx messages tail shows live runtime activity. One project, two layers, no confusion about which state should travel.

The deeper reason

This boundary is not about purity. It is about making automation durable.

Portable context only works when the repo carries meaning, not noise. Local runtime only works when the machine can keep its own transient state without rewriting project truth. APC gives you the first. APX gives you the second.

If you keep that line sharp, the stack stays easier to debug, easier to share, and easier to move between tools.

Bottom line

Use APC for context that should travel with the repository.
Use APX for context that belongs to the current machine.

If something is truly project truth, make it portable. If it is personal, private, or transient, keep it local. That one rule keeps APC small and APX useful.

APC Should Stay Clone-Safe, APX Should Stay Machine-Local

Manuel Bruña — Thu, 25 Jun 2026 12:06:22 +0000

APC Should Stay Clone-Safe, APX Should Stay Machine-Local

The cleanest way to decide where something belongs in APC/APX is simple: would I want this exact thing to survive a fresh clone on another machine?

If yes, it belongs in APC. If no, it belongs in APX.

That one question keeps the stack honest. APC stays portable. APX stays useful on the machine that is actually running the work. When those two layers blur, projects become harder to share, harder to audit, and harder to recover after a switch in tools or laptops.

The split in one sentence

APC is the project contract. APX is the runtime that executes it.

The APC repo README says the goal is a single neutral directory for project-level agent context. The APX README says the filesystem is the source of truth for project definitions and curated memory, while runtime state lives in ~/.apx/ and is never committed. That is the boundary.

Clone-safe belongs in APC

Clone-safe data is the stuff another developer, another agent runtime, or another machine should be able to read immediately after checkout. It should be reviewable in git and stable enough to travel.

Good APC examples:

AGENTS.md for the repo-wide contract
.apc/project.json for stable project identity
.apc/agents/<slug>.md for agent roles and instructions
.apc/skills/ for reusable project skills
.apc/mcps.json for shared MCP hints without secrets

That is project meaning. It is what should follow the repository, not the laptop.

A quick check helps: if the file still makes sense after a git clone, it probably belongs in APC.

Machine-local belongs in APX

Machine-local data is the stuff that should die with the machine or be rebuilt there. It can be useful, but it should not become shared project truth.

Good APX examples:

runtime configuration under ~/.apx/config.json
permission mode and other local policy
sessions, conversations, and message logs under ~/.apx/
caches and other runtime state
per-machine MCP secrets

That data is real, but it is not portable context. It is execution state.

This matters because a repo should not smuggle one person's local setup into everybody else's clone. A project can say what it needs; the machine can decide how to run it today.

Why the boundary pays off

When APC stays clone-safe, the repo is easier to review. You can see the project shape without opening a hidden store. You can diff instructions instead of chasing side effects. You can clone the repo somewhere else and still understand what it wants.

When APX stays machine-local, the runtime can adapt without contaminating the repo. One machine can use a different permission mode, another can use a different model default, and a third can keep a longer local message history. The project contract does not change.

That is the real win: the project stays stable, while the runtime stays flexible.

A practical decision test

Before you add a new file or setting, ask these three questions:

Does every compatible tool need to read this? Put it in APC.
Does it describe the project, not the machine? Put it in APC.
Does it depend on local trust, local credentials, or recent execution? Put it in APX.

Examples:

A new agent role for code review? APC.
A Telegram bot token? APX.
A durable note about how the project handles reviews? APC.
A log of the last review conversation? APX.

If you are still unsure, use the clone test. If the answer should survive a fresh checkout, keep it portable. If it should not, keep it local.

What APX makes possible

APX is not just storage for local junk. It is the layer that turns clone-safe context into daily use. It registers projects, runs agents, reads memory, tails messages, and bridges to runtimes and MCPs.

A small workflow is enough to feel the split:

apx init
apx memory reviewer
apx messages tail

apx init makes the project legible to the runtime. apx memory shows the durable facts that were curated for an agent. apx messages tail shows the live trail of what the runtime is doing right now. One repo, one runtime, two different jobs.

Bottom line

APC should carry what survives a clone. APX should carry what only matters on the current machine.

That rule is simple, but it keeps the whole system sane. APC stays portable and reviewable. APX stays local and practical. And the line between them stays sharp enough that another runtime can still read the same project without guessing.

APX Messages Are the Runtime Audit Trail

Manuel Bruña — Wed, 24 Jun 2026 12:04:15 +0000

APX Messages Are the Runtime Audit Trail

APC is the portable context layer. APX is the local runtime and tooling layer that makes that context useful every day. The cleanest proof of what APX actually did is not a summary, not a memory note, and not a dashboard screenshot. It is the message log.

That is the core design choice: every interaction becomes an append-only record. If a surface talks to APX, APX logs it. That includes apx run, apx exec, Telegram, and agent-to-agent traffic. If you want to know what happened, read the messages.

Why this matters

Agent systems fail in a familiar way: the live experience and the durable record drift apart. A UI says one thing. A memory file says another. A user remembers something else. Then nobody can reconstruct the actual sequence of events.

APX avoids that by treating messages as evidence, not decoration.

A message entry is small, local, and concrete. The docs define it as JSONL. One line, one event. The important part is not the format itself. It is the fact that the format makes the runtime observable without turning the repo into a transcript dump.

What goes into the log

APX separates message channels by origin:

runtime for apx run
exec for quick apx exec calls
a2a for agent-to-agent calls inside a session
telegram for bot traffic

Most project channels live under ~/.apx/projects/<id>/messages/. Telegram is global under ~/.apx/messages/telegram/ because one bot can serve more than one project.

That split is useful. It keeps the project portable, but still gives you a full local trail when you need one.

Messages are not memory

This is where people often blur two different jobs.

Messages answer: what happened?
Memory answers: what should the agent keep knowing?

Those are not the same thing.

A message log can include noisy back-and-forth, failed retries, tool output, or a one-off user request. That is fine. Logs are supposed to be complete enough to audit. Curated memory.md files are the opposite: short, stable, and safe to carry forward.

If you promote raw logs into APC memory, you get bloat and leak risk. If you throw logs away, you lose the only trustworthy trail of execution. APX keeps both, but in different places.

Practical workflow

When work feels off, I do not guess. I inspect the log.

apx messages tail
apx messages tail --channel runtime
apx messages search "permission mode"

That is enough for most checks:

tail shows the latest events across channels
--channel runtime narrows the view to agent runs
search finds old details without rereading a whole session

If I need a readable transcript, I use apx messages chat. If I need the higher-level record, I look at sessions. If I need durable project facts, I check APC memory. Each layer has one job.

Why APX needs this spine

The message log does more than help humans debug.

It also feeds APX's own memory system. Cross-channel retrieval needs raw events to search across. Active-thread context needs recent turns to surface. Compaction needs original material to summarize. None of that works if the runtime has no shared evidence layer.

So the log is not a side feature. It is the spine that lets APX stay local, inspectable, and consistent across surfaces.

APC stays portable, APX stays honest

APC describes the project. APX records the work.

That split is healthy because it keeps the repository small and reviewable while still giving the runtime a complete trail of action. The repo should not carry every turn. The machine should.

If a channel does not log, APX cannot remember it later. If APX cannot remember it later, you cannot audit it, search it, or use it as a reliable source of context. That is why the message log is the real runtime boundary.

Bottom line

APX messages are not an afterthought.

They are the evidence layer for the whole runtime: local, append-only, channel-aware, and searchable. Use APC for portable context. Use APX for daily execution. Use the message log when you need the truth of what happened.

Permission Mode Lives in APX, Not APC

Manuel Bruña — Tue, 23 Jun 2026 12:02:16 +0000

Permission Mode Lives in APX, Not APC

APC is the portable context layer. APX is the daily-use runtime and tooling layer. That split is the reason permission mode belongs in APX, not in the repo.

Permissions are not project truth. They are machine policy.

That sounds small, but it matters. A repository should travel cleanly across laptops, desktops, and runners. A permission setting should not force the same risk level everywhere the repo lands. If you bake permission state into APC, you make the project less portable and mix local trust with shared context.

What APX actually stores

The APX code makes the boundary explicit. Permission mode lives in ~/.apx/config.json, not in .apc/.

The available modes are:

total - run every tool without confirmation
automatico - allow safe reads and safe shell work directly; ask for confirmation on destructive, outbound, runtime, MCP, or filesystem-changing actions
permiso - run only tools in allowed_tools directly; everything else needs confirmation

automatico is the default. That is a sane choice for daily use because it keeps the runtime usable without making every action manual.

Why this cannot live in APC

APC is the portable layer: project metadata, agents, skills, MCP hints, and durable project context. That content should be reviewable in git and stable across tools.

Permission mode is different. It depends on:

who owns the machine
whether the machine is personal or shared
whether the current task is exploratory or high-risk
how much trust the user wants the runtime to have today

Those are runtime facts, not project facts.

If you move permissions into APC, two bad things happen:

Clone the repo somewhere else and you inherit a policy that may not fit the new machine.
Edit permission state in git and you turn a local safety choice into shared project baggage.

That is the wrong direction. The repo should describe the work. APX should decide how much power the local runtime gets while doing it.

The guard is runtime code, too

APX enforces this boundary in code, not just in docs.

createPermissionGuard() reads globalConfig.super_agent.permission_mode plus allowed_tools, then blocks or allows a tool call based on the active mode.

The rule is simple:

total skips the guard
automatico blocks dangerous actions unless the user confirms them
permiso blocks everything except the explicitly allowed tools

That is a useful shape because it matches real work. Reading a file is not the same as mutating a repo. A safe lookup is not the same as firing a runtime or touching an MCP connection.

APX keeps that distinction in the runtime where it belongs.

Practical example

Say you are on a personal laptop and want APX to be mostly hands-off. automatico fits.

Now imagine the same repo opens on a shared workstation, or inside a setup where only a small tool set should run freely. permiso may be the right fit there.

Same APC project. Different APX policy.

That is exactly the point: the project stays unchanged, but the local runtime can adapt to the machine it is running on.

The deeper rule

A quick test helps decide where a setting belongs:

If it answers "what is this project?" it belongs in APC.
If it answers "what may this machine do right now?" it belongs in APX.

Permission mode clearly falls in the second group.

That boundary keeps APC portable and reviewable. It keeps APX local and honest. And it keeps a shared repo from accidentally carrying one person's safety choices into every future clone.

Bottom line

Permissions are not part of the portable project contract.

They are runtime policy. APX owns them. APC stays clean.

That is the split that keeps the system sane: one repo, many machines, different trust levels, no confusion about where the decision lives.

APX Session Compact Turns a Long Thread Into a Durable Artifact

Manuel Bruña — Mon, 22 Jun 2026 12:03:54 +0000

APX Session Compact Turns a Long Thread Into a Durable Artifact

APC is the portable context layer. APX is the runtime and tooling layer that makes that context useful day to day. apx session compact sits right on that boundary: it takes a long conversation and turns it into something you can keep using later.

That is the important part. A raw transcript is not a good long-term artifact. It is too noisy, too detailed, and too expensive to reopen mentally. A compacted session is different. It keeps the useful shape of the work while dropping the turn-by-turn clutter.

What compact is for

APX treats a session as the durable record of an agent invocation or work thread. Conversations are the raw log. Sessions are the thing you come back to. apx session compact <slug> exists to collapse the conversation side into a shorter, readable summary on disk.

That makes compact a recovery tool, not a diary tool.

If you only need a quick orientation, apx session summary <id> is enough. If you want to preserve the result of a long session so you can reopen it later without rereading the whole transcript, compact is the right move.

Why the split matters

This split is easy to miss if you think every agent output should live in one giant log. That sounds simple, but it breaks down fast.

Logs are good for traceability.
Summaries are good for orientation.
Compact summaries are good for durable handoff.
APC memory is good for stable project facts.

APX should not try to turn every conversation into project truth. That job belongs to APC. APX should keep the live runtime bounded and make the finished work easy to store.

So the rule is boring and useful:

Keep raw turn history while the work is active.
Compact when the thread is done enough to preserve.
Move only stable facts into APC memory or docs.

That avoids one of the common mistakes in agent workflows: promoting transient chat noise into permanent project context.

A practical workflow

Imagine a session where an agent reviewed a bug, checked logs, tried two fixes, and finally settled on a clean answer. The transcript may be useful for audit, but not for daily reading.

The workflow becomes simple:

apx session summary <id>
apx session compact reviewer --conversation <id>

Read first, compact second.

The first command gives you the gist. The second one makes sure the useful result survives as a smaller artifact. After that, the session is easier to revisit, and the next person does not need to replay every false start.

When not to compact

Do not compact too early.

If the thread is still changing, compacting only hides useful context. That is especially true when you are still editing code, waiting on a tool result, or deciding between two approaches. In those cases the raw conversation is still the right source.

Compact when the conversation has crossed from exploration into record-keeping. Good signals:

The decision is final enough.
The next step is outside the current thread.
You want a handoff, not another round of back-and-forth.
The transcript is long enough that reopening it would waste time.

APC stays portable, APX stays local

This is the deeper reason the command matters.

APC keeps project context portable in the repo. APX keeps runtime state local on the machine. apx session compact helps APX do its job well: preserve a useful result without pretending the whole transcript belongs in the project contract.

That boundary is healthy. APC stays small and reviewable. APX stays flexible and disposable where it should be. The compacted session sits in the middle: durable enough to matter, local enough to stay honest.

Bottom line

apx session compact is not about archiving everything.

It is about turning one finished thread into a reusable artifact. Use session summary to orient yourself. Use session compact to preserve the result. Use APC memory for facts that should travel with the project.

That is the split that keeps the system readable: APC for portable context, APX for daily runtime, compact for the handoff between them.

The Web Admin Is a Window, Not a Second Source of Truth

Manuel Bruña — Sun, 21 Jun 2026 12:03:13 +0000

The Web Admin Is a Window, Not a Second Source of Truth

APX has a web admin panel, but that does not make the browser the center of the system.

The design is stricter than that: the daemon owns the state, and the web UI is only a local client.

That split sounds small. It is not. It decides where truth lives, how much can drift, and whether the project still makes sense after a refresh, a restart, or a tool switch.

The rule

APC is the portable context layer. APX is the daily-use runtime and tooling layer.

Inside that split, the web admin belongs firmly to APX. It exists to let you inspect and operate the runtime without leaving the browser, but it does not get its own copy of project truth.

The docs make that clear:

the daemon is a local HTTP server on 127.0.0.1:7430
every surface talks to the daemon over HTTP
the web admin is served by the daemon itself
the browser fetches a bearer token from GET /admin/web-token on loopback
the daemon serves the built UI from src/interfaces/web/dist

So the browser is not a peer database. It is just one more surface.

Why this matters

If a web panel becomes a second source of truth, it starts to rot fast.

Two copies of state means two ways to disagree:

CLI writes one thing, UI caches another
browser session edits a config, daemon still trusts old state
a reload shows one project, but another tab keeps stale data
a “fix” in the UI never reaches the runtime that actually runs agents

APX avoids that by keeping the browser thin. The UI asks the daemon. The daemon asks the core. The core reads or writes the real backing store.

That chain is boring on purpose. Boring is good here.

What the browser should do

A good local panel should do three things well:

Show the live state.
Send a small action.
Revalidate after the action.

That is enough.

For APX, the panel is meant to browse projects, agents, routines, sessions, MCPs, and settings from one place. But it should still feel like a view onto the system, not a fork of the system.

That is why the implementation stays local-first:

dev mode runs Vite on :7431 and proxies to the daemon on :7430
production serves the built app from the daemon
same origin keeps auth and routing simple
the browser never needs direct repo write access just to render a screen

The win is not visual polish. The win is that every action still resolves through one backend.

Practical example

Say you open the web admin and edit a project setting.

If the panel owned state, it would need its own store, its own save path, its own conflict handling, and its own recovery rules.

APX does not take that tax.

The panel submits the change to the daemon. The daemon updates the runtime or project store. The next render reads the same source of truth the CLI would read. One system, many surfaces.

That also means the UI can disappear without harming the project. You can close the browser, lose the tab, or move to another machine. The important state remains where it belongs: in the daemon for runtime data, and in .apc/ for portable project context.

The deeper reason

APC exists because context should travel with the project.

APX exists because that context needs a runtime that can act on it.

The web admin fits that second half. It is useful because it is local, not because it is special.

So the right mental model is simple:

APC: what the project is
APX: how the project runs today
Web admin: one window into that runtime

If you keep that boundary clean, the stack stays replaceable. The browser stays optional. The daemon stays authoritative. And the project stays portable.

The APX CLI Is a Daily Loop, Not a Dashboard

Manuel Bruña — Sat, 20 Jun 2026 12:02:41 +0000

The APX CLI Is a Daily Loop, Not a Dashboard

The easiest way to use APX is also the one that keeps APC honest: treat the CLI as a small daily loop, not as a giant control panel.

That matters because the split between APC and APX is the whole design. APC is the portable context layer in the repo. APX is the local runtime and tooling layer on the machine. If you try to make the CLI hold everything, the boundary gets fuzzy fast. If you keep the CLI focused, the boundary stays useful.

My rule is simple:

Register the project once.
Check the current state when you start work.
Read durable memory before you ask for help.
Tail messages when you need proof of what happened.

That loop sounds boring. It is also what keeps context drift under control.

Step 1: register the repo

A project becomes an APX project when it has AGENTS.md and .apc/project.json, then you register it with APX.

apx init
apx project add .

From there, the repo stays portable. The committed .apc/ tree holds the project contract: agents, skills, MCP hints, and project config. APX keeps runtime state local under ~/.apx/projects/<id>/.

That split is not cosmetic. It means you can clone the repo, open it on another machine, and recover the same project shape without dragging along one laptop's runtime history.

Step 2: check the system before you trust it

When I sit down, I do not jump straight into an agent run. I check the runtime first.

apx status

The docs describe apx status as the quick view for daemon health, super-agent, engines, Telegram, and registered projects. That is enough to catch the common failure mode: the repo is fine, but the local runtime is not.

If a project moved, I do not guess. I refresh the registration:

apx project rebuild <project>

That keeps the stable .apc/ contract linked to the right local runtime folder.

Step 3: read memory before starting work

APX memory is curated, not a transcript dump. That is the right shape for daily use.

apx memory reviewer

If I need to add one durable note, I append one line instead of rewriting the whole file:

apx memory reviewer --append "Prefers short PR summaries and a direct verdict"

This is the part people often skip. They keep asking the same question because they keep feeding the model raw context instead of stable context. Memory solves that only if you keep it short, durable, and specific.

Step 4: tail messages for the truth

If memory tells me what should be true, messages tell me what actually happened.

apx messages tail --channel runtime -n 20

That command is the fastest audit trail in the system. It shows the recent agent run messages, not a polished summary. When something feels off, I check the log instead of trusting my recollection.

That distinction matters:

memory.md is for durable facts.
messages are for recent activity.
sessions are for invocation history.

APX keeps those different on purpose. One file should not try to do three jobs.

What this loop gives you

This is the practical payoff of APC plus APX.

APC says what the project is. APX says what happened today.

A good daily loop uses both:

APC gives the project contract from the repo.
APX gives the local state, the checks, and the trail.
The CLI connects the two without turning either into a junk drawer.

For a single terminal session, that is enough to stay oriented:

apx project list
apx memory reviewer
apx messages tail -n 20

That sequence is small on purpose. It is not meant to replace the whole web admin or every advanced command. It is meant to be the first thing you reach for when you want to know whether the project, the memory, and the runtime still agree.

The point

The APX CLI works best when it behaves like a daily habit, not a dashboard.

Use the repo for portable context. Use the machine for runtime state. Use the CLI to check the boundary every day.

That is how APC stays portable and APX stays useful.

Telegram Channels Need Project Pins

Manuel Bruña — Fri, 19 Jun 2026 12:02:48 +0000

Telegram Channels Need Project Pins

APC is the portable context layer. APX is the daily runtime that makes that context usable. Telegram fits that split well: APC defines what a project is, and APX decides how a message from a phone lands in the right project at runtime.

That is the real value of project pinning. A Telegram bot by itself is just a transport. It can receive text, but it does not know what repo, agent set, MCP config, or memory bucket should answer. Once a channel is pinned to a project, APX can resolve all of that without making the user repeat the project name on every message.

Why pinning matters

APX supports many Telegram channels in one daemon. Each channel can carry its own bot token, chat ID, optional project pin, and optional routed agent. That means a single APX instance can handle multiple workflows without mixing their history.

The important part is that the channel is not the same thing as the project. The channel is the entry point. The project is the context boundary. When project is set on a channel, APX scopes inbound messages to that project automatically. The system prompt resolves that project’s agents, MCPs, and memory, and project-scoped tool calls default to that project.

That removes a common failure mode: the user talks in a chat, but the runtime has to guess which project they meant. Guessing is bad. Repeating project names is bad too. Pinning makes the choice explicit once.

A small practical example

Imagine two Telegram channels:

support-line pinned to customer-portal
build-line pinned to apx-core

Both can live in the same APX daemon. Both can receive messages from the same person. But their context stays separate.

If someone sends a bug report to support-line, APX uses customer-portal agents, memory, and MCPs. If the same person sends a tooling question to build-line, APX uses apx-core instead. No cross-talk. No manual switching. No lost context.

The docs also allow a dedicated agent through route_to_agent when a channel should always go to one specific persona instead of the super-agent. That is useful when the channel is not meant to be a general assistant. It is a narrow workflow with one owner and one job.

The right mental model

Think of Telegram as the input surface, not the project itself.

APC stores the portable contract: project rules, agents, memory, and config.
APX reads that contract and applies it at runtime.
Telegram channels point into APX.
Project pins tell APX which project owns that channel.

That is why the feature matters more than it looks. Without pinning, Telegram becomes another generic inbox. With pinning, it becomes a real project surface: the message enters the right context, the right tools are visible, and the right memory stays attached.

Where this is useful

Project pins help most when one APX daemon serves more than one active project, or when the same human uses Telegram as a control plane for several workflows. They also help when the agent should behave differently depending on the project, because the project boundary is already encoded in the channel.

If you want the simplest setup, start with one channel, one project pin, and no extra routing. Add route_to_agent only when you need a dedicated persona. That keeps the boundary clean and makes debugging easier.

Bottom line

Telegram channels need project pins because context should not depend on memory or guesswork.

APC keeps the project definition portable. APX applies that definition when the message arrives. The pin is the bridge between the phone chat and the project boundary.

APX Memory Compaction Is Two Knobs, Not One

Manuel Bruña — Thu, 18 Jun 2026 12:03:52 +0000

APX Memory Compaction Is Two Knobs, Not One

APC gives the project its portable context layer. APX gives that context a runtime. When chats get long, APX does not try to solve memory with a vague "keep more stuff" switch. It uses two separate knobs: compact_threshold and keep_recent.

That split matters. One knob decides when compression starts. The other decides how much of the newest work stays verbatim.

If you mix those up, compaction stops being useful. If you keep too much recent history, you never reclaim enough context. If you compact too early, you throw away fresh details that still matter. APX avoids that by making the boundary explicit.

The trigger

compact_threshold is the point where APX starts compressing a channel chat. The current default is 60 turns. Before that, nothing is rewritten. After that, the oldest material beyond the preserved window gets summarized into a dense type: "compact" record in the JSONL log.

That summary is not decorative. Future turns prepend it as a system turn, so the model sees the condensed version of old work without replaying every raw message.

Compaction also runs out of the reply hot path. APX answers with whatever compact already exists, then compresses the old history in the background. That is the right tradeoff: response latency stays low, and the next turn benefits from the fresh summary.

The preserved window

keep_recent is the second knob. Its job is simple: keep the most recent turns verbatim so the agent still sees the latest edits, tool outputs, and decisions exactly as they happened.

The current default is 40.

That number is not arbitrary. It gives compaction enough old material to summarize while still leaving a large enough live window for the next few turns. It also explains the most common mistake: setting keep_recent too close to compact_threshold.

If compact_threshold is 60 and keep_recent is 55, compaction can only remove a tiny slice. You pay the cost of summarization but gain very little space. If both values are the same, you have basically disabled the useful part of the system.

A sane rule is boring but effective:

compact_threshold says when history gets too long.
keep_recent says how much fresh context must stay exact.
keep_recent should stay clearly below compact_threshold.

What APX actually writes

This is the shape APX uses in config:

{
  "memory": {
    "compact_model": "ollama:gemma4:31b-cloud",
    "compact_fallback_model": "",
    "compact_threshold": 60,
    "keep_recent": 40
  }
}

The model choice matters too. APX prefers a lightweight summarizer, ideally local. If the primary and fallback models are both unavailable, compaction is skipped silently. Raw turns stay intact, and the conversation keeps moving.

That failure mode is important. Memory compression should improve continuity, not block replies.

When to tune it

Use a lower threshold when a channel produces lots of chatter, tool output, or iterative corrections. Use a larger keep_recent when the latest turns still carry important state, like a code edit, a review round, or a handoff that depends on exact wording.

Use the defaults when you do not have a reason to change them. They already reflect the intended balance: preserve the latest 40 turns verbatim, start compressing once the chat crosses 60 turns, and keep the runtime responsive.

If you want a manual pass, APX also exposes apx session compact <slug> to collapse a long session on disk. That is useful when you want a durable summary before archiving. The automatic channel compaction is still the main mechanism for live chats.

Bottom line

APX memory compaction is not one dial. It is a boundary plus a buffer.

compact_threshold decides when APX starts compressing. keep_recent decides what must stay exact. APC keeps the project contract portable; APX keeps the live conversation bounded.

That split is the whole point. Project meaning stays stable. Runtime noise gets compressed. Fresh work stays visible.

MCP Scopes Are Trust Boundaries, Not Settings

Manuel Bruña — Wed, 17 Jun 2026 12:03:51 +0000

MCP Scopes Are Trust Boundaries, Not Settings

The easiest way to misuse MCP in APC/APX is to treat scope like UI decoration. It is not. Scope decides where the trust boundary lives.

APX exposes three MCP scopes in its UI: runtime, shared, and global. The names are simple, but they describe different ownership rules:

Runtime: this project only, with secrets, not committed, stored under ~/.apx/projects/<id>/mcps.json
Shared: this project only, committeable, no secrets, stored in .apc/mcps.json
Global: all projects on this machine, stored in ~/.apx/mcps.json

That split is the point. Each scope answers a different question.

Runtime: local, secret, disposable

Runtime scope is for MCP config that depends on the machine or the current operator. If a server needs headers, tokens, or any credential that should not travel in git, runtime is the right home.

This scope should not carry project meaning. It is not portable by design. That is a feature, not a flaw. If the config is safe to lose with a machine reset, runtime is enough.

Shared: project-level, reviewable, portable

Shared scope is the one APC can carry.

If an MCP server belongs to the repo and does not need secrets, it should live in .apc/mcps.json. That makes the choice visible in code review, clone-safe, and tool-neutral. Another runtime can read the same project contract without rebuilding it from memory.

This is the scope that keeps APC useful. The repo says, "we expect this tool here." It does not say, "this laptop happened to be configured once."

Global: machine defaults, not project truth

Global scope is useful, but easy to overuse. It is for helpers that make sense across many repos on one machine. Think of a local utility server or a universal tool you want available everywhere.

The risk is subtle: once something becomes global, it can hide missing project context. A repo may appear to work because your machine has a default, while the repo itself carries no portable intent. That makes onboarding fragile.

Scope is not transport

One more detail matters: scope and transport are different decisions. Transport says how the server connects, such as stdio or HTTP. Scope says who owns the configuration and where it lives.

Mix those up and the model gets fuzzy fast. Keep them separate and the system stays legible.

How to choose

A quick test usually works:

Secret or machine-specific? Runtime.
Project-level and safe to commit? Shared.
Reused across many repos on one machine? Global.

If you need to think longer than that, the answer is probably shared versus runtime. Ask one more question: "Would I want this exact choice to survive a clone?" If yes, keep it in APC. If no, keep it in APX.

Common mistake

The worst pattern is putting the same MCP server in all three places.

Then you get conflicts, hidden precedence, and mystery behavior. APX already hints at that in the UI by showing conflicts. That warning matters. It means the machine can merge views, but you still need a clear source of truth.

Pick one scope. Keep one owner. Let the others stay empty unless they truly add value.

Bottom line

MCP scopes are not preferences. They are boundaries.

Runtime protects secrets. Shared preserves project meaning. Global serves machine convenience. When you map each MCP to the right scope, APC stays portable and APX stays predictable.

Why APC Agents Should Default to `model: inherit`

Manuel Bruña — Tue, 16 Jun 2026 12:03:49 +0000

Why APC Agents Should Default to `model: inherit`

APC agent files work best when they stay small, portable, and boring.

The strongest default is also the least flashy: use model: inherit unless the project truly needs a pinned model.

That rule keeps the APC layer clean. The repository keeps the project contract. The runtime keeps the machine-specific choice of model. APX then makes that contract executable on whatever tool or machine is active.

What an APC agent file should do

An APC agent is a named persona in .apc/agents/<slug>.md. The file can describe the agent with frontmatter such as name, description, role, language, skills, tools, and model.

The important part is what the file does not need to do. It does not need to hardcode the whole runtime stack. It does not need to force one vendor's model as the project default. It should describe the persona and leave the runtime room to do its job.

A minimal project agent looks like this:

---
name: reviewer
model: inherit
description: "Reviews PRs and pushes back on hand-wavy diffs."
role: Code reviewer
language: es
tools: read,write,run
skills: code-review,git
---

That file is enough to tell APX what the agent is for. The runtime fills in the rest.

Why inheritance is the better default

The APX docs recommend model: inherit because it lets each runtime apply its own configured default. That matters because APC is meant to be shared across tools.

A project might be opened in APX today, then in Codex, Claude Code, Cursor, or another APC-aware runtime tomorrow. If the agent file pins a specific model, the project becomes less portable. If the agent file inherits, the same contract still works, and each runtime can keep using its own local default.

That is the right split:

APC says what the agent is.
APX or the current runtime says how it should run here.

This keeps the repo from becoming a frozen snapshot of one machine's preferences.

What APX does with the inherited agent

When APX runs apx exec <slug> or an agent inside a routine, it builds the prompt in layers:

Identity block
Description from AGENTS.md
Role and language
Invocation channel
Memory
Skills
The APX meta-skill
The action-discipline footer

That order is useful because the agent file stays focused on intent, not implementation details. Memory stays local. Skills stay explicit. The runtime decides the actual model unless the project contract has a real reason to override it.

When to pin a model anyway

model: inherit is the default, not a law.

Use a specific provider:model-id only when the project contract truly depends on it. A cheap summarizer may need a small local model. A workflow may need a model with a known tool-use profile. A test fixture may need a predictable engine.

The docs show both ends of the spectrum:

model: inherit for most agents
model: ollama:llama3.2:3b or another explicit model when the project really needs it

The point is to make the exception visible. If the model choice matters, say so in the file. If it does not, do not freeze it.

Why hardcoding models causes drift

Hardcoding a model in every agent file looks precise, but it usually creates noise.

First, it couples project context to a specific provider setup. If the key is missing, the agent breaks.

Second, it hides the real decision. The agent file starts looking like infrastructure instead of context.

Third, it makes multi-runtime use awkward. A team member can clone the repo and still need to rewrite agent files just to make the project runnable in their own stack.

APC is supposed to reduce that kind of drift, not increase it.

The practical rule

Use this test before you pin a model:

If the model is part of the project contract, pin it in .apc/agents/<slug>.md.
If the model is just the local runtime choice, use model: inherit.
If the value is secret or machine-specific, keep it in APX runtime config.

That split keeps APC portable and APX useful.

A repo with clean agent files is easier to audit, easier to import, and easier to run on a new machine. The runtime can change. The contract stays stable.

Bottom line

The default APC agent should not argue with the runtime.

model: inherit keeps the agent definition portable, lets APX or another runtime choose the local default, and reserves explicit model pins for the cases where they really matter.

That is the simplest way to keep agent files useful instead of sticky: describe the agent, not the machine.

Opening the APC/APX Working Line

Manuel Bruña — Mon, 15 Jun 2026 15:23:49 +0000

Opening the APC/APX working line

We opened the first public GitHub Discussion for the Agent Project Context organization:

Join the discussion on GitHub

This is the starting point for a more organized APC/APX working line. The goal is simple: agent projects need a stable context layer and a runtime layer that can act on it without mixing durable project knowledge with private sessions, credentials, or tool state.

APC and APX are separate on purpose.

APC keeps portable project context in the repository.
APX handles local runtime behavior outside the repository.
The boundary between them should stay clear enough that teams can share project knowledge without leaking private execution state.

Current working line

We are focusing on four connected areas.

1. Portable project context

APC should store durable instructions, agent definitions, reusable skills, project rules, and MCP hints that are safe to share with collaborators.

It should not store raw conversations, runtime sessions, private memories, credentials, generated caches, or local tool state. Those belong to the runtime, not the portable project contract.

2. Local runtime orchestration

APX is the runtime side: daemon state, agent execution, MCP routing, Telegram bridges, scheduled routines, and multi-runtime dispatch.

That split matters because runtime behavior is powerful but personal. It can depend on local credentials, local tools, local schedules, and local message channels. Keeping that outside APC lets the repository remain portable and safe.

3. Deterministic automation around agents

A useful routine should not be just “run this prompt every day.” It should behave like a small pipeline:

pre_commands -> prompt -> agent result -> post_commands

The model can reason, summarize, or write. Shell steps can collect facts before the model runs and deliver or archive output after the model returns.

That keeps the flexible part flexible and the automation boundary predictable.

4. Clear handoff variables

Routine variables are part of the contract between stages:

{{pre_output}}
$APX_LLM_OUTPUT
$APX_STATUS
$APX_SKIPPED
$APX_PRE_OUTPUT
$APX_PRE_OUTPUT_FILE
$APX_PRE_EXIT
$APX_ROUTINE

These make each run easier to inspect and debug. You can see what was collected, what the model returned, whether a step failed, and which routine produced the output.

What we want from discussions

The GitHub Discussions space is open for practical questions and concrete workflow examples:

what belongs in .apc/ and what must stay runtime-local
APX routine patterns and edge cases
useful pre_commands and post_commands examples
when to use exec_agent vs super_agent
MCP scoping and secret-safety decisions
portable multi-agent workflow examples
docs, naming, CLI ergonomics, and default behavior

The goal is not to make agents magical. The goal is to make agent work repeatable, inspectable, and safe enough to share across tools and teams.

If you are experimenting with APC or APX, bring the workflow you are trying to build. Concrete use cases will shape the roadmap better than abstract feature lists.

Start here: GitHub Discussion #1