Agents Memory and Skills

One subject in two halves. A profile carries one knowledge domain it writes and the skills it may run (Agents § 0.1); both are governed the same way — owned by a domain, versioned, tested before publication, pinned per case, revertible (Agent Framework § 6) — and both answer the same measured failure of v1: knowledge that existed and did not fire, and work redone by reasoning every time it recurred. Part I is the memory: the tree, the protocol every agent inherits, what a domain holds, the dreaming pass, the past-case index, and how an inherited corpus crosses in on a measured result. Part II is the skills: what a skill is, when one exists, how it is governed, what happens when it fails, and three samples. Both parts state principles, with one example each, and name no module's content: each module's branch of the memory tree and its skill catalogue are at the head of its module page, under its agent tree — Configuration Module § 0, Support Module § 0, Data and Information Module § 0, Development Module § 0 (D145, D151).

The memory convention is already estate practice [F: serdica-backend has a root AGENTS.md on master, and the AI branch carries 40 per-module AGENTS.md guidance files — inspected 31.08.2026]; the PC agent's routed 20-document library is the proven single-domain instance [F: artifact].

Part I — Memory

One writing profile per domain — profile, instance and domain are distinct (Agents § 0.1). Every node in the memory tree has an AGENTS.md index; the agent profile that owns the node boots from it, reads the whole tree, and writes nothing outside its own node.

1. The tree — the principle, and an example

P The shape. One tree. Its top-level branches are the platform's own knowledge, the connectors' knowledge (one node per system), and one branch per module. Below a module branch there is one node per thing that has an owning profile: a stage, a repository, a symptom family. A node exists because a profile writes it, never the other way round; a module's branch therefore has exactly the shape of its agent tree.

P The example — the two branches that belong to no module are real; the module branch is a schema, and each module page draws its own instance:

memory/
├─ AGENTS.md                          ← the protocol (§ 2)
├─ platform/
│  ├─ AGENTS.md                          sessions, gates, audit, runtime operations
│  ├─ intake/AGENTS.md                   source identity, normalisation and intake entitlement (Agents § 5c); classification belongs to Support
│  ├─ experience/AGENTS.md               the platform's case record — what was asked, what was accepted, per customer
│  └─ handovers/AGENTS.md                the consult catalogue and the handover packet per direction
├─ connectors/
│  ├─ AGENTS.md                          index of systems
│  └─ <system>/AGENTS.md                 one per connected system: per-env scoping, error decode, session budgets
└─ <module>/                          ← one branch per module — drawn at the head of the module's page
   ├─ AGENTS.md                          the module's rules and the index of its nodes
   ├─ <stage or repository or symptom>/  one node per owning profile
   │  └─ AGENTS.md
   └─ experience/AGENTS.md               where a module keeps a past-case index (§ 5) — Support does; the others read it

P What one node holds — the AGENTS.md index (one-liners, one per article, in the proven v1 MEMORY.md shape), the articles themselves, and nothing that belongs to another node. Contents are mechanics of the running system — table chains, traps, rules, what breaks and how — never a narrative. A domain that is a stage holds what the stage agent needs to plan; a domain that is a system (a connector's) holds how to reach it and how it fails; a domain that is a repository holds its service index and its build truths.

P Seeds. Every domain is seeded from material that already exists — v1 memory articles, the PC agent's library, the estate's own guidance files — and every seed is a fact with a link. Migration is per domain and accepted on a measurement (§ 7), never big-bang. The seed list per domain is on the module page beside the node it seeds.

2. The root AGENTS.md — the protocol

The root file every agent inherits. Its outline P:

1. Boot. An agent starts from its own node's AGENTS.md plus the task prompt — not the whole chain; a consulted profile also boots from its own node, not a chain (D106). But it is required to be aware of the rest of the tree: the index of every domain is always available to it, and it reads any node it judges relevant, at any depth, without asking. Boot is light; awareness is total. Writing stays restricted to the own domain.

Why both halves matter: loading the full chain at boot is waste on a narrow task, while an agent that does not know the rest of the tree exists reproduces v1's failure — knowledge that is present but never consulted. 2. Writing practice. ATA Spec 100 discipline: declarative present tense, one subject per document, statements are fact (sourced) / plan / challenge. Articles follow the proven upkeep rules [F: the PC agent's knowledge-upkeep rule]: belief order running system → consuming code → memory; four kinds of wrong (wrong/stale/ambiguous/environment-specific) with four treatments; fix the claim where it is made; guide-not-diary (no dates/sessions/incidents in bodies — provenance in metadata; values replaced by the regenerating query); record the pattern, never the incident; no customer PII F: [rule]. 3. Dreaming protocol (§ 4). 4. Node creation — only if really necessary. A new node needs: recurring content, a distinct owning profile, and a retrieval need the parent index cannot serve. Creating one updates the parent AGENTS.md index in the same change. Anything less stays as entries under the existing node. The automatic path — a summarizer creating a node an agent actually needed — is Agents § 0.6. 5. Reading another domain versus asking its agent. Reading is unrestricted, and the question that matters is not may I but which of the two: - Read the articles when you need a fact — a table name, a known trap, a rule of the running system. This is the default: it is cheap, it needs no coordination, and the article was written to be read. - Ask the owning agent when you need judgement — whether this case is the exception, what a contradiction between two articles means, or what is not written down. A lateral consult is evidence, never authority (Architecture § 2). - Always ask after two failed attempts at an unknown contract [F: the PC 9951 run]. Two failures mean the articles do not cover the case, and a third read will not fix that.

Why reading is not restricted: the memory tree holds no secrets and no customer PII by construction (rule 2), so restricting reads would buy no confidentiality — it would only hide knowledge from an agent that needs it, which is v1's measured failure. The real cost of reading everything is context and money, not exposure, and that is what the boot rule addresses: an agent boots with its own node and reads outward on demand.

6. Cross-domain findings. Handed to the parent (if it owns the domain) or to an instance of the owning domain's agent — never written directly into a foreign domain.
7. Case-local memory, and confirmation before common storage. Anything an agent learns inside a case is written first into the case's papers, which persist with the case (Agent Runtime § 11.2) — per-session memory is never lost, and no other case retrieves it. A finding worth reusing is filed as a proposal into the target domain: a proposed-state entry, absent from normal retrieval; the originating case and explicitly assigned validation cases may read it as a labelled candidate. Only on confirmation — a human review, or two independent cases that used it without contradiction (§ 7.4b) — does the domain's owning profile write it into the shared tree as active, reusable by every case. A proposal is evidence with provenance, never authority, and never another profile's write (Trust and Data § 1).
8. Escalation. Doubt and dead ends travel upward; only root agents reach the human.

An example of the protocol at work. A stage agent meets an unknown write contract. First attempt: it reads its own node and the connector's node — the fact is not there. Second attempt: it reads the neighbouring domain's articles — still not there. Rule 5 now applies: it stops and raises a consult to the owning domain, whose profile answers from the same nodes with the judgement the articles lack (Agents § 5, D92). What the consult taught is written case-locally (rule 7), filed as a proposal into the owning domain, and becomes shared knowledge only when the owner confirms it.

3. What a domain holds, and what seeds it

P The rule is the same for every domain: the mechanics of the running system a profile needs to plan, the traps it has met, and the seeds it was built from — each seed a fact with a link. The instances differ by kind:

P The per-domain tables — domain · owning profile · contents · seeds — live on the module pages, directly under the module's agent tree, so a reader sees the profile and the node it owns in one place.

4. The dreaming protocol

When a case closes (mandatory pass) and on schedule (consolidation):

1. Harvest candidates from the case papers and report: what was learned, what was reused, what was missing.
2. Classify each: executable skill candidate (Part II) · article (pattern) · experience entry · index line only · nothing (justified in the report).
3. Write within the own domain, under § 2 writing practice; candidates for foreign domains become proposals the owning profile confirms into shared storage (§ 2 rule 7); skills go through the governance flow (test → publish, Agent Framework § 6).
4. Cross-domain candidates are handed to the parent or the owning domain's agent instance — with the evidence, as a request record.
5. Consolidate (scheduled): merge duplicates, prune stale entries against the running system, resolve or explicitly mark contradictions, refresh the node's AGENTS.md one-liners.
6. New nodes only per the § 2 gate; parent index updated in the same change.
7. Every memory write is an audit record; the case chat shows memory operations live (Platform PG-5).

5. A past-case index

P Case journeys adds canonical source-request identity, family, confirmed trigger and actual outcome to the experience paper. Occurrence, verified reuse and clean platform execution are distinct counters. Proposed SQL and owner reports can teach a mechanism but do not count as an executed platform write. Extended metadata lives in the immutable source paper linked from the experience entry; mirrors, forks and subcases retain their shared origin. Configuration and Development submit experience through the same curator; their profiles retain stage/repository knowledge ownership.

P The principle. Triage needs "has this been seen before" over cases, in seconds — and past cases are not articles. Whichever module keeps the estate's memory of what breaks keeps a sub-index with this entry shape; every module reads it, and one profile writes it. In the Bulstrad case study that module is Support, the index is support/experience, and its owning profile is the curator (Data and Information Module § 0).

• Entry: symptom signature (customer phrase + system error, verbatim) · systems/environment touched · mechanism found (one sentence, layer-named) · fix shape (data fix / config cell / code / answer) · links (analysis, KI, checklist, commit) · reusable artifacts (query pack, skill). No PII. Entries arrive as proposals from the agents that worked the case; the curator confirms them into shared storage (§ 2 rule 7).
• Indexes: a theme index (domain-grouped one-liners, the proven v1 MEMORY.md shape) + a symptom-signature lookup.
• Retrieval mechanics, granularity for multi-ticket sagas and staleness are stated once, for every past-case index, in § 7.3.

6. Reading another module's domain

P Every agent may read any node of the tree (§ 2 — boot is light, awareness is total). What it may not do is answer for a domain it does not own: a Configuration agent that reads the past-case index gets the articles, not the judgement. When the question needs judgement — has this shape failed before, and how does it fail? — the asking agent raises a consult, and the domain's own profile answers from the same nodes with the mechanics that go with them (Agents § 5). Why the distinction earns its keep: a past-case index is an index over cases, and reading an index without the methodology that built it is how v1's four documented error families recurred after their rule already existed.

P The past-case index is therefore written case-locally by the agent that worked the case and filed as a proposal; its curator promotes it into shared storage, read by every module. The platform's own case record — what a customer asked for and accepted, across modules — is platform/experience, a deterministic projection maintained by the platform's case-record handler; modules submit result references, not direct foreign-node writes.

7. Migrating an inherited corpus

AISA v1 holds 548 memory files, 509 ticket analyses (frozen baseline 31.08.2026), 56 known-issue entries and a set of living checklists (Baseline). That corpus is the platform's largest inherited asset and its most-cited goal (SG-7). It is also measurably not working as retrieval: the cross-session audit of 20.05.2026 found four error families recurring after the rule against them already existed F: [write-time discipline], while cached knowledge is 10–60× cheaper and 30–300× faster than rediscovery when it does fire F: [measurement].

So migration is not copying. Restructuring flat files into a tree changes where things live; it does not by itself make them fire. This section defines the method and, more importantly, the test that says whether it worked. The method is the same for any inherited corpus; v1's is the example.

7.1 The method

P The two memories are independent, and the migration is a one-time event (decision 01.09.2026). v1 keeps its own memory/; v2 has its own tree; neither writes into the other and nothing synchronises them. v2 supersedes v1 over time, and the corpus crosses once.

Why this is the simpler design: a shared tree during transition means two systems writing one domain, producing contradictions that neither notices. Independence removes that failure mode entirely, at the cost of a period where the same fact exists in both — acceptable because v1 is being retired, not maintained in parallel indefinitely.

P One-time does not mean one push: the migration is executed in waves (§ 7.4) so each domain is measured before the next starts (§ 7.2). What is one-time is the crossing itself — a domain migrates once, and after it has, v1's copy is no longer consulted for it.

Per domain, four passes:

1. Inventory — list the v1 files the domain's seeds name, plus what a grep of the domain's vocabulary finds. Record what was not taken and why.
2. Classify each item — mechanic (becomes pipeline behaviour or a skill, not an article), article (a pattern worth recalling), experience entry (a past case, § 5), index line only, or drop (superseded, environment-specific, or already true of the running system).
3. Rewrite under the writing practice (§ 2): declarative, one subject, guide-not-diary, values replaced by the regenerating query, the pattern not the incident, no customer PII.
4. Index — the domain's AGENTS.md one-liners are rewritten from the migrated content, not carried over.

P The classification is the point. v1's failure mode is that disciplines were stored as memory files that had to happen to fire. Anything that must always happen becomes a mechanic — a pipeline phase, a gate, an assertion, a skill — and is deliberately removed from the article set (Support Details SG-2).

7.2 The acceptance test

P Migration of a domain is accepted on a measured result, not on a file count:

Triage hit-rate on held-out cases. Hold back N resolved v1 cases the domain covers, excluded from the migration. Present each as it originally arrived. Measure how often the migrated domain surfaces the relevant precedent, mechanism, or checklist before investigation starts — and how often it surfaces a wrong one.

Recorded per domain: hit-rate, false-precedent rate, and time-to-first-relevant-item. The baseline to beat is v1's own retrieval — grep over flat files with one-line descriptions — measured the same way on the same held-out set. F Measured 02.09.2026 (Measurements § TB, scripts/triage_baseline.py): on 30 held-out resolved tickets, grep over the 619 MEMORY.md one-liners and KI titles finds a cited precedent in the top 5 for 3 of 30 (10 %), top-1 correct 1 of 30, 98 % of returned slots are noise, 7 tickets return nothing — Bulgarian symptom phrases against English one-liners are the main miss. This is the number every retrieval alternative (full article bodies, Bulgarian aliases, a vector index) is measured against on the same script.

P A domain that does not beat its baseline is not migrated; it is re-classified. Moving files without improving retrieval is the failure this test exists to catch.

7.3 The past-case entries

P Past cases are not articles; their entry shape is § 5. C Retrieval mechanics — title/grep index versus vector search (the estate retains Qdrant as a rebuildable index [F: docs/architecture/health-ai/00-program.md, inspected 31.08.2026]) — are decided by measuring § 7.2 on the migrated corpus, not by preference: both are cheap to try against the same held-out set. P Granularity for multi-ticket sagas — KI-anchored entries with case links first; a saga entry about one business object carries the keyed hash of the object number and never a person key (D44, Trust and Data § 4). P Staleness — entries carry the environment and version observed; re-verify before relying.

7.4 Order — the example

P Domains migrate in the order the tracks need them (Delivery § 1). For the first customer:

P platform/ has no v1 predecessor (§ 3), so it is written new rather than migrated. The domain names per wave are on the module pages.

7.4b Publication — memory is governed, not just written

P Candidate validation. A curator/owner may assign a proposed article revision to two explicit read-only validation cases. The candidate remains proposed, labelled derived, and absent from ordinary search. Each case records the article hash and an independent check against current evidence in MEMORY_USES plus its verdict paper. Cases must have distinct source-request identities; mirrors, subcases and forks of the proposing case do not count as independent uses. No contradiction and a passing check are required; mere retrieval is not a successful use. Until such evidence exists, use human review to promote.

P One canonical writer. The owner map is in Modules and MEMORY_DOMAINS. support.resolution owns support/methodologies; support.curator owns support/experience; each investigator owns its named symptom node. Curators/summarizers may draft for another node, but the owning profile activates the revision. A profile can own an explicitly listed set of nodes; ownership never follows whichever task happened to read one first.

P Memory is governed the way prompts and skills are — draft → test → publish — because the summarizer writes nodes automatically and memory informs without ever authorizing (Trust and Data § 1): an article that quietly misleads every future case is expensive even when it holds no authority.

P Every memory write carries provenance: which case, which profile version, which sources it was derived from, and whether a human ever reviewed it. An article whose provenance chain reaches untrusted content is marked as such and stays marked.

P Four storage/activation states, and the difference is what agents may do with an entry:

The shared tree holds only proposed/active/retired; the write into it is the owning profile's alone (§ 2 rule 7).

P Version pinning. A case records the article versions it relied on. When a later case contradicts an article, the earlier case's reasoning is still reconstructable — which is what makes a retraction traceable instead of a mystery.

P Rollback publishes a new version containing the previous accepted content, with its provenance and evaluation; retired records are not edited. Articles are immutable once active; a change is a new version.

P Dependency-scoped evaluation. Changing an article re-runs the eval sets of the profiles whose domain it sits in — not everything (CR-4 scoped by domain, per the cost envelope).

P The two-independent-uses promotion rule is the initial rule (decision 02.09.2026 — D56): it might promote a wrong article that happened not to be contradicted twice. Measure it on the migrated corpus before relying on it — the same held-out set as § 7.2 — and the rule is revised from that measurement, not from preference.

7.5 What is deliberately not migrated

P Workspace-operational memory that describes v1 itself — tool invocation quirks, connection state, session-handling workarounds — is not carried into the tree. It describes a system that is being replaced. Where such a file records a domain fact rather than a v1 mechanic, that fact is extracted and the wrapper dropped.

P The others/, hdesk/ and emails/ archives are evidence, not memory. Whether the past-case index links them in place or extracts entries from them is decided in wave 3, on the retrieval measurement.

Part II — Skills

A skill is an operation the platform can execute — inputs, connector calls, assertions, dry-run and teardown — governed like a prompt and bound to a memory domain (Agent Framework § 6.6). Agents are capable of doing everything a skill does by reasoning; a skill exists where doing it by reasoning costs an hour of tokens and time every time. It is the executable half of what a domain knows: the article says how the system behaves, the skill does the recurring thing to it and checks that it did. Which skills a module needs, with the ticket evidence behind each, is on that module's page under its agent tree (§ 13).

8. What a skill is — the anatomy P

Every skill carries the same five parts, and a skill that cannot state one of them is not ready to be published:

Around the five parts: a dry-run default — the packet is simulated before it is promoted unless the recorded exemption test passes (PG-21); a teardown for every write, emitted by the same skill in the same step (D120); and a coverage map where more than one write path exists — per configuration object, whether the system's own endpoint, a guarded statement or a gateway sequence carries it, and why (D136). The manifest that declares all of this is a draft contract, skill-manifest.schema.json (Contracts § 2, D139).

P A skill is the deterministic half of the work. It binds an instruction to connector tools plus assertions; what it cannot settle mechanically it hands back to the agent as a typed finding. Reasoning decides whether and which; the skill decides how, and checks that it did.

9. When a skill exists — the evidence rule and the ladder P

The hour rule. A shape becomes a skill when doing it by reasoning costs about an hour of tokens and time on every occurrence — that is where packaging pays for its own governance.

The ladder (Stage Precipitation § 2, D23): the platform counts occurrences on the fix signature; the third occurrence proposes the skill or the article, the seventh and the twentieth refine it with the evidence of use. A wrong existing claim is corrected at once, outside the ladder. The dreaming pass (§ 4) is where a case's candidates are classified as skill, article, experience entry or nothing.

The evidence rule. A skill proposed before the ladder reaches it — the seed catalogue a module starts with — is justified by ticket evidence, never by preference: how often the shape recurs, what it costs today, what it costs once packaged, and how many people can work it today (the bus factor). The method is mining the ticket archive with request-side keyword rules and analysis-side token rules, an effort class inferred per ticket, and the holder read from the ticket system's own tag F (Measurements § TM; the caveats — inferred effort classes, one ticket matching several shapes, the archive being the working set and not the whole desk — are recorded with the numbers). The numbers themselves, per shape, are on the module page that owns the shape; hours are estimates the ledger replaces (Value and ROI § 4), and their use is ranking, not accounting (D117).

P Two kinds of skill, one anatomy. A shape skill packages a recurring request — the case study's data corrections, account actions, document prints. A stage skill is what a module's stage runs to do or to prove its own work — a write path through a system's own configuration endpoints, a test that drives a quotation, a snapshot with a signature. Their evidence differs (the ticket stream for the first, the module design for the second); their parts do not.

10. Governance P

A skill is governed exactly as a prompt and an article are (Agent Framework § 6; § 7.4b above): its source of truth is Markdown in the memory tree, owned by its domain; publishing writes the catalogued, versioned runtime row with permissions; a running case keeps the version it started with (pinned) while workers reload at the next turn boundary; rollback is selecting the previous version. A skill that writes carries its dry-run default and its teardown with it, and its own tests re-run before an amended version is used; a skill the modules gate on re-runs its eval set as well (CR-4). Customer packs ship as plugins (Architecture § 1).

P A skill never widens a grant. It runs inside the case's grants, through the write executor and past the write auditor like any other write (Gating § 6); the only things a skill adds are certainty about the packet and a recorded classification.

11. What happens when a skill fails P

P A skill is the work's only path, so a broken skill is a work item, not an obstacle to route around. The agent finishes the case and repairs the skill — diagnose, correct the skill or the tool it calls, re-run it, and let the corrected run produce the result. Doing the step by hand and leaving the skill broken is not a completed case: the same failure returns on the next case, and what was learned survives only in one transcript.

P So a case that met a skill defect closes with three artefacts — the delivered work, the amended skill or tool, and the memory entry naming what it could not do before (§ 4). The amendment is itself a change: a skill's own tests re-run, and a skill the modules gate on re-runs its eval set before the amended version is used (Agent Framework).

P Two bounds keep this from becoming open-ended. Improvisation stops at two attempts — after two failures against an unknown contract the agent asks the peer who owns it rather than trying a third time or substituting a manual step (P-15, Product Configurator § P; § 2 rule 5). And a defect that is not the skill's to fix is a gate, not a repair: a missing endpoint, a backend constraint or a frontend component is Hd to the Development module, which is a legitimate result rather than a workaround.

12. Three samples P

One per kind, each read as inputs → read set → classification → write packet → verification, with the v1 material that seeds it. The full catalogues these come from are on the module pages (§ 13).

13. Where the catalogues are

The same page holds each module's branch of the memory tree (§ 0.1), so a reader sees a domain, its owner, its seeds and the skills bound to it in one place.

Challenges

• P The manifest is a draft (D139): a small required core the platform validates and an open body a case may extend; it graduates only after three modules' cases stop extending it.
• P Effort classes behind the catalogues are inferred, not measured. The ledger replaces them after the first month; until then a catalogue ranks, it does not budget. Recorded with the numbers on the module pages.