DEV Community: Agent Project Context

A Project Needs Two Memories—But Only One Should Travel With Git

Manuel Bruña — Mon, 05 Oct 2026 12:03:57 +0000

A Project Needs Two Memories—But Only One Should Travel With Git

Agent projects collect facts quickly: a deployment detail mentioned in a chat, a local preference discovered during a run, a decision that belongs in the repository. Treating all of them as one memory creates a bad choice: either private runtime details leak into Git, or durable project knowledge remains trapped on one machine.

APX and APC avoid that choice by giving a project two memories with different jobs. The practical rule is simple: let APX retain newly captured project notes locally; promote only reviewed, team-safe facts into APC.

The memory that stays local

APX keeps local project memory under its own runtime state, outside the repository. This is the right destination for facts gathered while operating: a note from a conversation, a temporary constraint found during a task, or a detail that may include information not meant for every future clone.

That separation is deliberate. A note captured automatically can contain material supplied through a chat or session. Committing it immediately makes it durable, shared, and hard to retract. Local runtime memory lets APX use the fact during daily work without silently turning it into project policy.

For example, an agent may record that a current task depends on a local service configuration. That can help the next APX turn on the same machine. It does not automatically mean every contributor should inherit it.

The memory that travels

APC's .apc/memory.md has a stricter role: curated project facts safe for the team. It lives in the repository, so Git carries it through clones, reviews, and history. That makes it useful for decisions that should outlast a runtime session: an architectural boundary, a durable convention, or a confirmed operational constraint.

The important boundary is authorship. APX does not treat a newly captured runtime note as permission to write the curated APC file. A person reviews the fact and decides whether it belongs in the shared project contract. The Memories surface can show both halves, but their visibility does not erase their different trust levels.

Why two memories improve daily work

A single memory store forces every note to be either too private to share or too easy to commit. The two-part design gives each fact a safe first home:

Capture working context locally in APX.
Keep using it while the local runtime needs it.
Review whether it is durable and safe for the team.
Promote only that smaller set into .apc/memory.md.

This also keeps APC portable. A fresh clone receives the decisions needed to understand the project, not another operator's conversations or machine-specific residue. Meanwhile, APX remains useful as the local runtime that can retain short-lived operational context.

The thesis is not that local notes are lesser knowledge. They are knowledge with a different audience and lifetime. APC makes shared context explicit; APX makes daily context usable without confusing it for a Git artifact. Keep both, but promote deliberately.

A Local Agent Panel Should Not Need a Cloud Project Mirror

Manuel Bruña — Sat, 03 Oct 2026 12:03:44 +0000

A Local Agent Panel Should Not Need a Cloud Project Mirror

A browser panel can make an agent system feel like a hosted product. That does not mean the project must be copied to a hosted product. APX takes a different boundary: the panel is a local interface to a local daemon, while APC keeps durable project context in the repository.

That distinction is practical. A project needs rules, agent definitions, reusable skills, and curated memory that can travel with its Git history. A running system needs sessions, conversation threads, logs, a scheduler, and active connections that should stay on the machine operating them. Treating both as one cloud-shaped data store weakens both jobs.

APC is the portable context layer. Its project contract lives in AGENTS.md and .apc/: files a teammate can review, version, and clone. APX is the daily-use runtime layer. It reads that context, runs agents, and keeps runtime state under ~/.apx/ instead of turning the repository into a session database.

The panel is a surface, not another source of truth

APX's web admin is served by the local daemon. By default, that daemon listens on 127.0.0.1:7430; the CLI, web panel, desktop window, TUI, and MCP bridge communicate with the same local process over HTTP. One runtime can therefore expose several interfaces without making each interface own a separate copy of projects, agents, or conversations.

Start with a normal status check:

apx status

If needed, APX starts its daemon. Opening http://127.0.0.1:7430 then shows the panel backed by that same daemon. The browser is useful because it is a good surface for browsing projects, sessions, messages, MCPs, and routines—not because it becomes a new project backend.

This design avoids a common drift problem. Imagine editing an agent role in a dashboard while the repository still has an older agent definition. Now a reviewer must ask which source an agent will actually follow. APC avoids that ambiguity by keeping durable project meaning in ordinary files. APX can index and use those files, but its live state remains runtime-owned.

Local by default, explicit when shared

A local panel is not automatically a network service. APX binds the daemon to loopback by default. To open the panel from another device on a LAN, the operator must opt in and pair that client. That is a meaningful boundary: browser access can expand deliberately without silently exposing the daemon on every network.

The same separation helps with recovery. Removing a project from APX's registered-project list does not delete project files. Cloning the repository elsewhere still brings the APC contract; it does not bring someone else's local conversations, tokens, or daemon process.

There is no claim that local runtime state eliminates every external dependency. An agent may call a configured model provider or an MCP server. The point is narrower: APX does not require a public server merely to give a local project a usable agent dashboard.

Use the boundary as a design test. If a fact should survive a clone and code review, put it in APC. If it only exists because an agent is running right now, let APX keep it local. The panel can be rich without becoming a cloud mirror of your project.

Read Your Own AGENTS.md Whole; Bound Foreign Context

Manuel Bruña — Fri, 02 Oct 2026 12:03:01 +0000

Read Your Own AGENTS.md Whole; Bound Foreign Context

An agent runtime has two conflicting duties when it loads project instructions: preserve the rules that govern its own work, and keep an arbitrary external file from consuming the entire prompt. Treating both files the same creates a bad trade-off. A small universal limit can silently remove a project’s own critical rules; no limit lets any referenced repository take over the context window.

APX makes the distinction explicit. It treats APC as the portable context layer: AGENTS.md and the defined .apc/ files carry project-owned guidance. APX is the daily-use runtime and tooling layer that assembles this guidance into a live prompt, along with runtime state that remains local.

The practical rule is simple: APX reads the AGENTS.md for the project it is running inside in full. A foreign project’s file has a configurable budget.

Why one cap fails

Imagine a project’s AGENTS.md starts with code conventions and ends with a release safety rule:

## Release

Never publish before the integration suite passes.

A fixed cap can preserve the first section and cut the last one. The agent then receives a partial contract while believing it received project guidance. That is worse than a visible absence: it can follow some rules and violate rules it never saw.

APX had exactly this failure mode. Its prompt-builder regression test records that an earlier 6,000-character cap sliced the owning project’s contract mid-rule. The current implementation does not cap the project matching the runtime’s working directory. The project’s own contract reaches the prompt whole.

That is not a claim that every instruction file should be unlimited everywhere. It is an ownership decision. The repository running the agent owns its contract and should be able to review its full effect.

Foreign context needs a different policy

APX can also receive a project path that is not its own working project. That file might be useful context, but it is not safe to assume its size is reasonable for the current turn. APX therefore applies a default foreign-contract budget of 24,000 characters.

When it must shorten a file, it does two important things:

It cuts on a line boundary instead of breaking a rule mid-sentence.
It states that the result is truncated and reports how much was omitted.

The resulting prompt tells the agent to read the file directly before relying on rules not shown. This preserves an important fact: partial context is partial.

The foreign cap is also configurable through super_agent.project_agents_max_chars. A positive value changes the budget; 0 disables it. That makes prompt size a deliberate local runtime choice, not a hidden change to APC’s portable contract.

Keep the boundary clear

This division helps answer a common design question: should a project shorten its own instructions to fit a runtime? Sometimes, yes—but that should be a project authoring decision, made in the repository and reviewed like any other change. It should not be an invisible runtime truncation.

Likewise, a runtime may need to bound external context for cost and reliability. That safeguard belongs in APX, where prompt assembly happens. It does not redefine what APC files mean or what a project is allowed to document.

A useful test follows: when an agent acts inside your repository, can you show exactly which project rules reached it? If the answer is “only the first part, silently,” the boundary is wrong. Read the owning contract whole; bound foreign context visibly.

APC keeps the contract portable. APX applies it in a live runtime without pretending every source of context has the same ownership or budget.

Why APX Rejects Invalid Agent Autonomy Instead of Guessing

Manuel Bruña — Wed, 30 Sep 2026 12:03:19 +0000

An agent autonomy setting looks like small metadata. It is not. It can decide whether a tool runs now or pauses for a human. That makes guessing the wrong response to invalid input.

APC provides portable project context: agent files, roles, skills, and project metadata travel with the repository. APX is the local runtime that reads that context, runs agents, and enforces tool permissions on the machine. The boundary matters here: a portable agent declaration may request an autonomy mode, but APX must turn that declaration into a real, local permission decision.

APX has three permission modes:

total: tools run without confirmation.
automatico: safe work can proceed; destructive, outbound, runtime, MCP, and filesystem-mutating work can require confirmation.
permiso: only allowed_tools run directly; every other tool asks.

A project has a baseline mode in its runtime configuration. An individual agent can declare Autonomy: to override that baseline for its own turn. An agent with no declaration inherits the project setting.

The bad shortcut

Imagine a project whose normal setting is automatico, and a review agent should be more constrained:

---
name: reviewer
role: Review pull requests
Autonomy: permiso
---

Now imagine someone edits the card and writes Autonomy: permissive. A permissive parser might map that to total, choose the nearest known word, or silently save a value that later means something else. Each path turns a typo into an authorization decision.

APX does not invent a mode. When it reads a stored autonomy field, an unrecognized value is dropped and the agent inherits the project baseline. That protects the runtime from treating garbage as a new, wider permission setting. It also keeps the effective policy explainable: either a recognized agent override applies, or the project policy applies.

There is an important nuance. Inheritance is not a substitute for validation. If the project baseline is broader than the author intended for that agent, a malformed stored value will not magically preserve the intended restriction. That is why APX handles direct CLI input differently: apx agent ... --autonomy rejects an invalid value and tells the user the accepted modes, including inherit. A person at a terminal gets a visible error instead of a plausible-looking success message.

A practical rule

Use these meanings consistently:

no --autonomy flag     keep current agent setting
--autonomy inherit     clear agent override; follow project mode
--autonomy automatico  set explicit agent override
--autonomy permiso     set explicit agent override
--autonomy total       set explicit agent override

Then verify the result in the agent file and test an action that should pause. Configuration text alone is not evidence that the tool loop uses it. APX applies a valid agent override to the active turn configuration before its permission guard and risk handling run.

Keep the contract small

The portable side should say who the agent is and, when useful, its intended operating boundary. The runtime side must decide what the current machine can actually execute, prompt on, or deny. APC does not become a hidden authorization database; APX does not treat a typo as authority.

That division makes agent behavior safer to review. A teammate can inspect the declared agent contract in the repository. The local runtime can enforce it without copying private runtime state back into APC. And when an autonomy value is wrong, the system has one honest answer: stop guessing and fix the value.

A Portable Agent Contract Cannot Link to a Local Plan

Manuel Bruña — Tue, 29 Sep 2026 21:45:16 +0000

A Portable Agent Contract Cannot Link to a Local Plan

An AGENTS.md file can tell every compatible agent how a repository should be handled. That promise breaks when a rule links to a planning file that exists only on one developer's machine. The link works for its author, then becomes a dead end in a fresh clone.

This is a small boundary, but it is a useful test for portable context. If a future contributor cannot read an instruction and every document it depends on, the instruction is not yet a project contract.

APC is the portable context layer. It keeps repository-owned rules, agent definitions, skills, and non-secret MCP expectations in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It runs agents and keeps local operational material—sessions, private runtime memory, caches, and machine-specific state—outside the repository.

A local plan belongs on the APX side of that boundary unless it has been deliberately promoted into a shareable project artifact.

A link is an ownership claim

Consider this root instruction:

Read `spec/release-notes.md` before changing the deployment flow.

If spec/ is ignored because it holds exploratory notes or raw QA evidence, a new clone has neither the file nor its reasoning. The root contract now asks an agent to follow unavailable context. Worse, a reviewer can miss the error because the author's working tree resolves the link perfectly.

The same problem appears with absolute paths, private issue exports, temporary design notes, and runtime logs. They may be useful during one task. They cannot be prerequisites for portable behavior.

Treat every link from AGENTS.md, .apc/, or tracked documentation as a claim: this target is durable, safe to share, and available to a clean checkout. If that claim is false, change the contract.

Promote the decision, not the scratchpad

A local plan often contains valuable thinking mixed with temporary material. Do not copy the whole file into APC merely to repair a broken link. Extract the part that survives review.

For example, a local release investigation might establish one lasting rule: generated assets must be checked before publishing. That rule can live directly in AGENTS.md, or a concise explanation can become a tracked decision document. The raw command output, incomplete alternatives, and machine paths remain local.

A practical promotion flow is:

Keep the working plan and raw evidence local while the task is active.
Identify the decision that future contributors actually need.
Rewrite it as a short, self-contained project rule or tracked document.
Link only to that tracked artifact from APC context.

This gives a clean clone enough guidance to act without importing private or stale task history.

Use the smallest durable surface

Not every note needs a new document. A repository-wide instruction belongs in AGENTS.md. A reusable procedure can become an APC skill. A rule for only one folder belongs in .apc/rules/. A longer, reviewable rationale can live in ordinary tracked project documentation.

The important part is not the filename. It is whether the content remains true, readable, and useful beyond the machine that produced it.

APX helps keep the other category useful without pretending it is portable. Its local runtime can retain sessions, messages, task state, and private working material under its own storage. That lets an active task keep detail without leaking that detail into the repository contract.

Fresh-clone test

Before adding a context link, ask one question: would this still help an agent that cloned the repository today on another machine?

If yes, keep it tracked and make the target self-contained. If no, leave it in the local plan or runtime state, then promote only the verified conclusion when it becomes a real project constraint.

Portable context is not a directory full of references. It is a contract that can stand on its own. APC carries that contract; APX carries the local work around it.

A WhatsApp Capability Should Capture, Not Execute

Manuel Bruña — Mon, 28 Sep 2026 12:03:50 +0000

A WhatsApp Capability Should Capture, Not Execute

A contact asks a WhatsApp agent for an appointment. The dangerous interpretation is: the agent now has permission to book one. APX uses a narrower interpretation: the agent may capture the request for its owner to confirm.

That difference keeps a conversational convenience from quietly becoming an execution path.

APC is the portable context layer. It keeps durable project material in the repository: AGENTS.md, .apc/, agent definitions, skills, commands, and MCP hints. APX is the daily-use runtime and tooling layer. It handles local channels, runtime state, identity, and the live decisions around an inbound message.

A WhatsApp request is runtime work. It should not turn into a portable project instruction—or an automatic external action.

Capabilities are deliberately small

APX's WhatsApp configuration recognizes three capabilities: appointments, errands, and facts. All start off by default.

The names can be misleading if read too quickly. They are not tool grants. A non-owner WhatsApp turn has no tools. Enabling appointments or errands lets APX extract a request into a pending suggestion; it does not let the conversation book, send, promise, or decide anything.

The split matters because answering someone and acting for them are different kinds of authority. A natural reply can say, “I’ll pass that along for confirmation.” It must not say a time is agreed, a slot is free, or an errand will happen.

facts is the other deliberate boundary. When an owner has written approved facts for a contact, APX may answer from those facts. Anything outside them remains unknown. A friendly contact-specific rule can adjust tone, but it cannot create facts or tools that the runtime did not supply.

Capture runs beside the reply

For enabled appointment or errand capture, APX reads the inbound message separately and records a structured pending suggestion. It preserves the sender, request summary, requested work, urgency, and the sender's timing words.

That last detail is important. If somebody says “tomorrow afternoon,” APX stores those words rather than resolving them into a timestamp. The capture layer is not allowed to make a calendar decision merely because it understood the phrase.

APX also keeps capture separate from the reply text. Hiding machine-readable request data inside a reply would require stripping it before delivery. A failed strip could expose internal machinery to the contact. With a separate capture pass, the reply stays plain text and a capture failure only loses a suggestion; it does not corrupt the conversation.

A practical flow

Imagine a plumber writes:

Can I come by tomorrow afternoon to check the leak?

With appointment capture enabled, APX can create a pending request containing the contact, purpose, and exact timing language. The owner receives something to review. The agent's reply can acknowledge the request and say it will be passed on.

It cannot confirm the visit. It cannot claim the owner is available. It cannot turn “tomorrow afternoon” into a booking.

This is less flashy than an agent that acts immediately, but it is more truthful. The system knows it has captured intent, not completed the work.

Why APC stays out of it

The project may travel between repositories, machines, and compatible tools. WhatsApp contacts, owner approval, pending requests, and channel-specific capabilities should not travel with it as committed project truth. They depend on a particular account, operator, and moment.

So APC describes what the project is. APX handles what a local messaging surface may safely do today.

The useful rule is simple: when a message asks for real-world action, first capture intent. Then let a responsible human—or an explicitly authorized execution path—confirm the action.

A channel capability should make a request visible. It should not silently make that request true.

A Conversation ID Is Not Project Context

Manuel Bruña — Sun, 27 Sep 2026 12:02:59 +0000

A Conversation ID Is Not Project Context

A conversation ID can feel like the fastest way to give an agent continuity: save it in the repository, pass it to the next machine, and resume where the last prompt stopped. It is also the wrong boundary. A conversation is runtime state. Project context is a contract. They should not be stored together.

APC is the portable context layer. Its AGENTS.md and .apc/ tree describe the project: agent roles, reusable skills, project metadata, and MCP hints without credentials. APX is the daily-use runtime and tooling layer. It runs agents and keeps the local operational record: sessions, conversations, messages, caches, and task logs.

That split is not a limitation. It makes a clone predictable.

A conversation belongs to one local runtime

When APX registers a project, its committed definition remains in the repository. Its runtime data lives under ~/.apx/projects/<apx_id>/. Per-agent folders include sessions/ and conversations/; those files reflect a particular machine, engine, account, model context window, and moment in time.

A saved conversation ID may depend on all of those conditions. Another machine might not have the underlying conversation, might use a different runtime, or might not have permission to read it. Committing the ID makes the repository imply a guarantee it cannot provide.

The same mistake appears in a subtler form: copying a raw transcript into AGENTS.md or .apc/memory.md so the next agent can “continue.” Raw turns include temporary questions, stale tool output, and often sensitive operational detail. They grow quickly while teaching future agents what happened once, rather than what must remain true.

Keep the durable decision, not the handle

Suppose an agent investigated a deployment failure and found a durable rule:

The deploy command needs a clean generated-assets directory; run the project check before publishing.

That rule can become a reviewed project instruction or a concise curated memory fact. It can travel in APC because it explains an ongoing constraint. The conversation ID that led to it should remain local to APX, where an operator can inspect or summarize it when needed.

The resulting workflow is small:

Run work through APX; it records the local session and conversation.
Extract only stable, reviewable decisions.
Add those decisions to APC-owned instructions when they apply to the project.
Let a new machine register the repository and start a new local runtime history.

For a short-lived task, the durable output may be nothing. That is healthy. Not every discussion earns a permanent place in project context.

Portability needs a clean restart point

A clone should be able to answer: Which agents exist? Which rules apply? Which skills can run? Which project ID connects this repository to local APX state? APC provides those answers without importing one machine’s chat history.

APX then supplies the operational continuity appropriate to that machine: apx conversations list can inspect stored conversations, and apx session summary <id> can turn a completed session into a concise explanation. Those are runtime tools, not repository format requirements.

This separation also makes cleanup safer. Removing local runtime state does not erase repository rules. Sharing a repository does not publish chat transcripts. Switching from one supported runtime to another does not require pretending that an opaque conversation handle is a portable artifact.

Use APC to preserve what collaborators need to know before work begins. Use APX to retain the local evidence of work already done. A conversation ID can help one runtime resume a thread; it should never become the project’s memory contract.

A Routine Result Is Not a Delivery

Manuel Bruña — Sat, 26 Sep 2026 22:16:39 +0000

A Routine Result Is Not a Delivery

A scheduled agent can finish its work and still fail the person who asked for it. The model produced text. The shell command exited. The routine history says it ran. But its result never reached a human.

That is why APX treats routine output and routine delivery as separate steps. A result is what the routine produced. Delivery is where that result actually goes—and whether that route accepted it.

APC is the portable context layer: repository-owned rules, agent definitions, and skills that travel with a project. APX is the daily-use runtime and tooling layer. It runs a scheduled job, chooses its local delivery channels, and records the operational outcome. This is runtime behavior, so it belongs in APX, not in APC.

Delivery is opt-in

APX resolves delivery in a deliberate order:

The routine's own deliver_to setting.
The runtime default at config.routines.deliver_to.
No delivery.

That final default is intentional. A newly introduced delivery feature should not change where older routines send output. A routine must opt in before its result becomes a message on a channel.

For example, a routine can calculate a daily status and produce a useful answer. Without a configured delivery target, it has completed computation—not communication. The distinction prevents a misleading green checkmark.

One output, one owner

A second failure mode is double delivery. A routine can send a Telegram message itself, run a post_commands shell hook that sends the same text, and also have configured delivery. One logical report then becomes several notifications.

APX checks for channels already served by the routine handler, its post-command sinks, or an agent tool call. It suppresses the redundant path rather than assuming every configured route should fire.

This changes how to design a routine. Pick one delivery owner for each channel:

{
  "kind": "exec_agent",
  "spec": {
    "agent": "default",
    "no_tools": true,
    "prompt": "Summarize today's status in one short paragraph."
  },
  "deliver_to": ["telegram"]
}

The routine creates the text; configured delivery owns the Telegram send. Alternatively, a hand-written apx telegram send "$APX_LLM_OUTPUT" post-command can own that send. Do not configure both as independent paths for the same message.

A failed route should look failed

APX records a result for each delivery channel: ok, held, or error. An unknown channel is reported as an error rather than silently ignored. If delivery was requested but no channel accepted the message—and no earlier path already served it—the routine ends in an error state with a direct explanation: it produced an answer and no one received it.

held is different from failure. It means an interruption or notification budget deliberately withheld the message. The result remains available in the run log and routine memory instead of being discarded or mislabeled as sent.

That distinction is useful operationally:

ok: result reached configured channel.
held: runtime deliberately delayed or withheld a notification.
error: route did not accept delivery; investigate configuration or service state.

Ordinary reports need less noise

For ordinary Telegram-bound routine reports, APX can record a pending delivery first. The daemon gives the owner a short grace period to open the agent chat and reply. If that happens, the delivery becomes answered and the extra notification is canceled. If it remains pending, a later sweep notifies the owner. Priority or anchor deliveries notify immediately.

This is a small product rule with a practical effect: a user who already saw the report does not receive an unnecessary second ping, while an unseen report does not vanish inside a routine log.

The useful test for a scheduled agent is therefore not only “did it run?” Ask:

Did it produce the intended result?
Which channel owned delivery?
Was that channel ok, held, or error?
Could another path have sent the same report twice?

Let APC carry the portable instructions that define the work. Let APX own the local execution and delivery record. A routine becomes useful only when its result reaches the right person exactly once.

A Routine Name Is Not Its Memory Key

Manuel Bruña — Fri, 25 Sep 2026 12:02:14 +0000

A Routine Name Is Not Its Memory Key

A scheduled agent task needs two kinds of identity. One is for people: a name such as daily-review. The other is for stored runtime state: a stable identifier that survives normal edits. Treating those as the same thing creates a subtle failure: edit a routine, and its history silently becomes someone else's problem.

APC and APX divide this responsibility deliberately. APC is the portable context layer: versioned rules, agent definitions, skills, and other project facts that can travel with a repository. APX is the daily-use runtime and tooling layer. It runs routines and keeps their local operational state outside the repository.

That division makes routine identity an APX concern.

Display names change; runtime state should not

In APX, a routine record has a human-readable name and a generated id. The name is how the CLI and a person find the routine. The ID is what APX uses for the routine's private memory path:

~/.apx/projects/<project-id>/routines/<routine-id>/memory.md

This is more than implementation detail. Routine memory can hold short, durable operational notes that help the next run. If an ordinary edit assigned a new identity, the routine would no longer read its old notes. The old directory would remain behind, and the newly edited routine would start with an empty memory as if it were new.

APX avoids that by carrying the existing ID forward when upsertRoutine rebuilds a routine record. The record may receive a new schedule, prompt, delivery target, or tool boundary, but its runtime identity remains stable. The same applies to created_at: editing a routine is not creating a second one.

The boundary prevents a common confusion

It can be tempting to put this state in APC because both systems are project-aware. But routine memory answers a runtime question: what should this specific scheduled task remember locally between runs? It is not automatically a team-wide project rule.

For example, a routine named daily-review might accumulate a short note about an unresolved local inspection. That note belongs to the APX runtime store. It should not appear in a clone just because someone copied the repository, and it should not become a committed instruction without review.

If the project eventually needs a durable rule—perhaps a verified deployment constraint—a human can promote that fact into APC through the normal review path. Until then, the local note stays local.

This boundary also keeps the two systems understandable:

APC names portable, reviewable project context.
APX names local execution state and connects it to a live routine.

A practical edit test

When changing a routine, verify more than its visible fields. Ask four questions:

Does the routine still have the same ID?
Does its existing memory path still resolve?
Did the edit preserve its creation time and prior run state?
If the name changes, is that an intentional new routine or a migration with an explicit state decision?

The last question matters because a display name is often the lookup key on a command line, while the runtime ID anchors data that should outlive routine edits. Renaming therefore deserves a deliberate product decision, not an accidental side effect of rewriting a JSON record.

Keep identity boring

Stable identifiers are rarely exciting. Their value appears when a routine changes over weeks: scheduled work keeps its own bounded history, local state does not leak into APC, and a harmless edit does not erase operational continuity.

Let APC carry portable project truth. Let APX keep routine state local. And when a routine changes, preserve the identity that its memory depends on.

Agent Memory Should Propose Before It Writes

Manuel Bruña — Thu, 24 Sep 2026 12:03:52 +0000

Agent Memory Should Propose Before It Writes

An agent can turn a busy day into a plausible list of facts. That does not mean it should silently rewrite the memory that shapes its next prompt.

That is why APX makes apx memory consolidate propose by default. It accepts candidate facts from standard input, evaluates them, and prints what it would keep or skip. Nothing is written until you add --apply.

This is a small CLI choice with a larger lesson: memory needs an explicit boundary between suggestion and authority.

APC is the portable project-context layer: committed agent definitions, rules, skills, and other reviewable project facts. APX is the daily-use runtime and tooling layer. It runs agents, keeps local runtime state, and provides the operational commands around it. The consolidation command belongs on the APX side because it works with runtime notebook memory, not repository context.

Candidate facts are not trusted facts

A routine, a model, or a person can send one candidate per line to the command:

printf '%s\n' \
  'Use pnpm, never npm' \
  'The owner may change the deployment plan next week' \
  'Review API changes before merging' | \
  apx memory consolidate

The important part is what does not happen: APX does not treat every line as memory. The command proposes a kept set and reports skipped candidates. Its implementation separates distilling candidate text from judging what survives, so the same rules apply whether candidates came from an automated routine or from a human at a terminal.

That protects against a common failure mode. Runtime activity is full of tentative language, stale details, copied text, and one-off task facts. If every summary automatically became long-term memory, the next prompt would inherit guesses as if they were instructions.

Preview is a real safety feature

When the proposed output looks right, write it deliberately:

printf '%s\n' \
  'Use pnpm, never npm' \
  'Review API changes before merging' | \
  apx memory consolidate --apply

The extra flag is not ceremony. Agent memory is injected into future prompts, so changing it changes future behavior. A background job that silently edits what an agent believes about itself can create hard-to-see drift: the job succeeded, but the agent is now operating from an unreviewed premise.

--apply makes that change visible at the point of action. It also gives operators a useful review loop: generate candidates, inspect the proposed keep/skip decision, then authorize the write only when the surviving facts deserve repeated prompt space.

Keep the scope honest

This command does not promote notes into APC automatically. APX per-agent memory lives under ~/.apx/projects/<apx_id>/agents/<slug>/memory.md, outside the repository. It is local runtime state. APC still holds the committed project contract, such as .apc/agents/<slug>.md and other portable context.

That distinction matters. A local notebook can help an agent work today without claiming that every note belongs in version control or should travel to every clone. If a fact later becomes stable, safe, and useful for the whole project, a human can curate it into APC through the normal review process.

APX also keeps reversal narrow. apx memory revert removes entries written by consolidation while leaving hand-written notes alone. That makes experimentation less risky: automated consolidation has a bounded undo path instead of treating the whole notebook as disposable.

Practical rule

Use automated processes to collect and compress candidate facts. Use explicit review and --apply to grant those facts long-term influence.

APC keeps portable project truth reviewable. APX makes local runtime memory useful without pretending that every observation is already truth.

For agent memory, that order matters: propose first, write second.

Give APC Skill Paths an Explicit Base

Manuel Bruña — Tue, 22 Sep 2026 12:03:42 +0000

A release skill can live in version control and still depend on one developer's laptop. The giveaway is often a path: /Users/alex/work/shop/docs/releases.md. Cloning the repository copies the instruction, but it does not make that address valid on another machine.

For project-owned files, write the location relative to an explicit repository root. That is a practical authoring convention, not a claim that APC automatically rewrites paths.

APC is the portable context layer: it carries shared project guidance. APX is the daily-use runtime and tooling layer that puts that context to work. Keeping those responsibilities separate helps expose a small but costly mistake: embedding the author's checkout location in a reusable procedure.

Give each path a base

The APC skills specification places reusable instruction files at .apc/skills/<name>.md. Agents can reference those skills from AGENTS.md or their agent definitions. The skill remains the shared source of the procedure.

Consider a fictional repository with this layout:

shop/
├── AGENTS.md
├── docs/
│   └── releases.md
├── scripts/
│   └── check-release.mjs
└── .apc/
    └── skills/
        └── release-review.md

A brittle instruction says:

Read /Users/alex/work/shop/docs/releases.md.
Run node /Users/alex/work/shop/scripts/check-release.mjs.

A more useful skill body says:

# Release review

All paths below are relative to this repository's root.
Before running commands, set the working directory to that root.

1. Read docs/releases.md.
2. Run node scripts/check-release.mjs.
3. Report the command's exit status and any failed checks.

Here, check-release.mjs is an example script that the fictional project owns, not an APX command or bundled capability. The skill tells the agent where to look and where to execute. A contributor can put the checkout under a different home directory without editing the procedure.

The explicit base matters. A bare docs/releases.md could otherwise be interpreted relative to the skill's directory, the shell's current directory, or a different checkout. Relative paths remove one machine dependency; naming the base removes the ambiguity they introduce.

Check the reference, not just the wording

Before merging a skill change, open the referenced document from the intended root. Check that the script exists in the repository and that its documented prerequisites are available. If the command changes files or publishes anything, review what it will do before running it merely to validate a path.

For a monorepo, specify the package directory when needed. An instruction to run a command from packages/storefront/ means something different from running it at the repository root. Keep that distinction in the procedure instead of expecting the agent to infer it from a filename.

A useful review exercise is to imagine the same checkout at two unrelated locations. Would every project-file reference still identify the same file? Would the command run against that checkout, or reach back into the author's original folder?

Keep actual machine dependencies visible

Some inputs genuinely live outside the repository: a private credential file, a local service configuration, or a separately installed tool. Turning those into invented relative paths does not make them portable. Describe the prerequisite and leave its machine-specific resolution to local setup.

The APC migration guide separates machine-local paths from shared project context. Applying that boundary to skill instructions preserves the team's procedure without committing someone's workstation layout.

APX can provide the execution environment, but the written contract should still explain its path assumptions. Start with one existing skill: replace hard-coded checkout prefixes, declare the reference root, and verify its targets. That small edit makes the next clone easier to use.

Explore the APC repository for the portable context format and APX for the runtime layer.

Your APX Android Connection Depends on the Paired Address

Manuel Bruña — Mon, 21 Sep 2026 12:02:59 +0000

An APX Android app that works at your desk can stop connecting when you unplug the cable. The installation may be fine. The daemon address saved during pairing can explain the failure.

The practical rule: choose and test the connection for the place where you intend to use the phone. A successful USB setup does not prove that the same address works over Wi-Fi or mobile data.

APC is the portable context layer: project instructions and definitions live in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer: its daemon manages execution and exposes surfaces such as the Android app. Moving to a phone changes how you reach that runtime; it does not move the project or daemon onto the phone.

Three addresses, three reachability limits

The APX Android installation guide documents three connection paths:

Connection	What the phone reaches	When it stops working
USB tunnel	Daemon through `adb reverse`	Cable disconnected
LAN address	Daemon on the local network	Phone leaves that network
Tailscale HTTPS address	Daemon through the same tailnet	Required devices or network path unavailable

With USB forwarding, http://127.0.0.1:7430 on the phone can reach the computer's daemon. The forwarding makes that possible. Without it, the phone's loopback address is not an address for your computer.

For LAN access, the documented setup is:

apx panel share
apx restart

Use the actual address reported for your machine. An example such as http://192.168.x.x:7430 describes an address shape, not a value to paste literally. This connection suits a phone and computer on the same reachable local network.

For access beyond that network, APX documents:

apx panel tailscale on

This uses Tailscale Serve and an HTTPS address inside the tailnet. It does not publish the daemon through Tailscale Funnel. Both devices need the appropriate tailnet connectivity, and the computer still needs to remain available.

Check the selected address after installation

The current guide says apx android install checks addresses the daemon serves against addresses the phone can reach. It prefers a working tailnet path and uses the USB tunnel as a fallback. That is useful automation, but the fallback matters: a successful installation may still leave you depending on the cable.

Start by inspecting the installation:

apx android status

This reports the attached phone, installed version, adb, and tunnel. Then check which daemon URL the app actually retained. For manual pairing, apx pair web provides a code and QR; enter the intended daemon URL in the app along with the code.

Test the intended path directly. For LAN use, disconnect USB and open the app again while staying on Wi-Fi. For away-from-home use, test with the phone off that Wi-Fi and connected to the tailnet. Read a fresh piece of daemon data so a previously rendered screen does not stand in for connectivity.

Keep the diagnosis narrow

If the app fails only after unplugging, inspect the stored URL and tunnel dependency before reinstalling. If it fails only outside the house, inspect whether it was paired to a LAN address.

Those symptoms point to reachability. They do not establish that the APK is damaged or that the project's APC context needs changing. Keeping that distinction clear gives you a small, repeatable check before touching an otherwise working setup.

The commands and Android client belong to the APX repository.