Bring Your Agents: The Import Pipeline

Your agent already has a memory. It's just scattered.

An agent you already run through a CLI harness isn't empty-handed — it has accumulated real knowledge in files the harness reads at startup: CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, and whatever project- or user-level instruction files that runtime uses. Import doesn't ask you to re-teach an agent what it already knows. It reads those files, distills the durable statements out of the boilerplate, and writes them into the agent's private Brain.

const found = await agentis.agents.discover_import();   // scans local harnesses
await agentis.agents.import({ agents: found.result.agents });   // identity + memory + skills

The distillation quality gate

Raw instruction files are mostly boilerplate — headings, code fences, installation steps, table-of-contents noise. A deterministic scorer walks every line and drops anything below a 0.55 quality threshold (DEFAULT_MIN_QUALITY) before it's even offered as a candidate. The scorer isn't a model call — it's fast, free, and repeatable:

Every surviving line becomes a candidate atom classified into a memory type — decision, failure, success_pattern, or distilled_lesson by default — and tagged with a suggested trust score derived from where it came from (an operator-authored project file is trusted more than a machine-global runtime default).

Idempotent by construction

Import is designed to be run more than once without ever polluting the Brain. Two independent dedup layers make that safe:

• Exact. Every candidate carries a content hash. Re-scanning an unchanged file produces the same hashes, which are recognized as already-imported and skipped — no new episode, no duplicate.
• Semantic. A paraphrase of something already in the Brain — same idea, different words — is caught by an embedding similarity search at a 0.82 cosine threshold. Instead of writing a near-duplicate, the existing episode is reinforced: its confidence and trust nudge upward, exactly as if the same lesson had been independently confirmed.

At the agent level, idempotency works the same way: the imported agent's config.importOrigin stores the external ID it came from, so importing "the same" Claude Code agent twice reuses the existing Agentis agent rather than creating a second one.

Import is the beginning: continuous ownership sync

After import, Agentis keeps the connection to the external harness as a durable ownership source. It scans once at startup, watches source directories for changes with a debounce, and runs a scheduled recovery scan so a coalesced or missed filesystem event cannot silently break synchronization. Every scan and every detected revision survives restart in agent_sync_sources, agent_sync_items, and agent_sync_runs.

The policy is granular: memory can require review or auto-apply above a configurable quality threshold; owned skills can be reviewed or auto-upserted; identity/persona/model drift can be reviewed separately; and source deletions can require review, reconcile automatically, or be ignored. Marketplace skills and low-quality memories enter quarantine regardless of the broad mode.

Deletion reconciliation is deliberately non-destructive. A removed source item creates an audited tombstone; an applied memory deletion archives the Brain episode instead of hard-deleting it. Skills and identity are never erased merely because an external file disappeared.

Where an atom lands: agent-private vs. workspace-shared

Not every imported statement belongs to one agent. A convention scoped to how this specific agent should behave lands in its private Brain (scopeId = agentId); a rule that applies to the whole team lands in the shared workspace Brain (scopeId = null). Import carries a scope hint per candidate so this routing happens automatically instead of dumping everything into one bucket.

Private Brain administration

The App or workspace Brain is global workforce knowledge, while a specialist's private Brain is its agent-scoped competence. The orchestrator can administer that private Brain with agentis.agent.brain.configure and verify the result with agentis.agent.brain.inspect; writes are idempotent and can include memories, knowledge, skills, and skill examples.

Skills come along too

A harness's SKILL.md files transition into agent-scoped Brain skill atoms — Living Skills — through the same import call. Re-importing a skill with the same name upserts it in place rather than duplicating it; marketplace/vendor skills are opt-in only, while the operator's own project and user skills are included by default.

Continue