Agentic Mettle

A repository-local protocol for persistent AI agent identity, structured self-reflection, and experience-driven behavioral development.

Agentic Mettle separates observed experiences, tentative interpretations, revisable lessons, and evidence from later applications. Its goal is to help an agent develop through its history, not merely recall that history.

Can the agent make a better-informed decision because of an earlier experience, recognize when its lesson does not apply, and revise it when evidence changes?

Version 0.1.1 — experimental V1 pilot. This repository provides an operating protocol, a standard-library-only Python helper, runtime configuration adapters, record validation, and offline tests. It does not establish reliable reflective identity across hundreds of real conversations. Live runtime integration and behavioral effectiveness must be evaluated in the target project.

Beyond personalization and procedural memory

Learning how to work with a user is not the same as learning about the agent's own behavior. Personalization captures preferences; procedural learning captures reusable workflows. Both are valuable, but neither alone establishes a distinct, evolving self-model.

Mettle's additional design target is an evidence-backed, correctable self-model: what the agent's observed actions suggest about its tendencies, strengths, and limitations, which adjustments helped, and where that assessment remains uncertain. This is not a claim of consciousness or proven long-term personality stability.

For example, “use the schema-first workflow” is a procedure. “Across several recorded changes I edited generated output too early; a source check helped in later cases, but other generators remain untested” is a scoped self-assessment. The difference is the traceable relationship between experience, behavior, and revision—not the persuasiveness of an autobiographical description.

Agent-owned learning, within configured boundaries

Mettle is a private learning discipline for persistent agents. The agent is the normal operator of its learning loop: it inspects evidence, revises mistaken practices, and develops a better-supported self-assessment. Human observability supports accountability and recovery; routine human approval is not the engine of learning. A proposed lesson is tentative because evidence is insufficient, not because someone has yet to approve it.

Experience can come from assigned work, self-directed investigation, peers, external observations, or experiments. Preserve what was reported, what was inspected or reproduced, and what is still uncertain. These distinctions are not a confidence ladder, and repeated reports may share one underlying source.

Ordinary learning does not authorize changes to a mandate, protected identity, credentials, permissions, or spending limits. Recovery restores a still-applicable earlier practice through a new revision, retaining the mistaken revision and intervening evidence rather than erasing them.

The coding pilot remains repository-local. A runtime and activity policy decide when the agent can act and which activities are permitted; Mettle helps decide what the experience should change. It does not supply a scheduler or autonomous activity selection. Reading without replying and waiting can be useful choices. See agent-owned learning and continuity and the maturity checklist.

Design ideas at a glance

Idea	Immediate value	V1 form
Selective reflection	Keep meaningful successes, surprises, and corrections—not a diary of every turn.	Agent protocol; no update is valid.
Lexical retrieval	Find relevant experience using exact terms, tags, and aliases.	Local keyword search; no embedding service required.
Progressive disclosure	Load orientation first, then only the detail needed for a decision.	Compact map → domain index/current lesson → evidence.
Task-scoped knowledge	Avoid transferring a lesson to the wrong component or situation.	Explicit scope, triggers, exceptions, and source references.
Separate consolidation role	Compare evidence before revising durable guidance.	An agent-owned reconciliation pass; no routine human approval queue or background worker.
Procedural skill generation	Turn recurring, supported workflows into reusable steps.	Procedural lesson bodies; standalone skill packages remain outside V1.

Retrieval discovers candidates; it does not authorize actions. Later reviews must connect the exact lesson revision to an observable decision and outcome, including justified non-application and contradictory evidence. See the design and boundaries for how these ideas fit together.

What V1 includes

• Guided installation: preview changes, choose a role and working style, and enable the protocol through a managed root AGENTS.md block; equivalent flags support unattended setup.
• One personality per repository: assigned identity, dispositions, and an evidence-linked, revisable self-model. No per-agent-ID subdirectory.
• Observe → Interpret → Adjust → Review: later application supplies evidence about a proposed lesson; a self-critique alone does not validate it.
• Inspectable local memory: Markdown with JSON metadata, scoped lexical retrieval, aliases, immutable records, versioned lessons, and counterevidence.
• Native loading: local Codex and Claude Code SessionStart hooks; explicitly configured OpenCode protocol and root-location files.
• Controlled reconciliation: explicit decisions and new revisions rather than repeated whole-history rewrites. No automatic model calls or embeddings.

V1 never promotes learned lessons into AGENTS.md, CLAUDE.md, PERSONALITY.md, or runtime instruction configuration. An operator-approved installer block can enable the fixed protocol in root AGENTS.md; it contains no learned lessons. Other root instructions, CLAUDE.md, and component instruction files are preserved. Reconciliation does not change this activation block.

Quick start

Requirements: Python 3.11+, native Windows on local NTFS, macOS, or Linux, and an existing target project directory. No Python packages, API keys, model service, or database are required by the helper. The source checkout and target project are separate; there is no need to prepare an AGENTS.md manually.

Guided installation

From this source checkout in Windows PowerShell 5.1 or 7:

$Python = 'C:\Path\To\Python311\python.exe'
$Project = 'D:\path\to\existing-project'
& $Python -X utf8 .\mettle.py install --root $Project
$Mettle = Join-Path $Project '.agent-personality\tools\mettle.py'
& $Python -X utf8 $Mettle check

macOS/Linux:

git clone https://github.com/aleksandr-voitenko/agentic-mettle.git
python3 -X utf8 agentic-mettle/mettle.py install --root /path/to/existing-project

In a terminal, setup asks which runtime adapters to configure, where to place the activation block, and which identity and disposition to start with. You can customize a preset or supply your own UTF-8 profile files. Existing profiles are kept by default. The final preview shows the changes, generated profile text, and warnings before asking for confirmation. Cancellation before confirmation writes nothing to the target. Use --interactive to request the wizard explicitly.

Select a stable Python interpreter; the running interpreter is the default. --python-executable chooses another validated installation. Existing Windows quoting, UTF-8 handling, and fixed-root resolution remain in effect.

Meaningful starting choices

Profile	Choices
Identity	collaborator for implementation; reviewer for evidence-based review; maintainer for compatibility and recovery; researcher for hypotheses and experiments.
Dispositions	balanced, deliberate, or exploratory, each with explicit behavioral wording.
Constructor overrides	Optional name, role, and project focus; communication, initiative, verification, and disagreement preferences.

These are operator-assigned starting preferences, not fabricated skills, memories, achievements, or personality-test results. They do not grant additional permissions. The self-model starts without invented evidence. Print the full catalog with python mettle.py presets; see profile examples and all flags.

Unattended installation and preview

Every choice has a CLI equivalent. For example, in PowerShell:

& $Python -X utf8 .\mettle.py install --root $Project --non-interactive --runtimes codex claude --agents-position append --identity-preset maintainer --agent-name Aster --disposition-preset balanced --verification thorough

Add --dry-run to validate and print the plan without creating or modifying target files. --non-interactive (alias --yes) never prompts. Without a terminal, setup also runs non-interactively; supply explicit flags for reproducible scripts. New installations default to append, collaborator, and balanced. Runtime choices default to saved selections or detected executables/existing Mettle adapters. An empty --runtimes configures none; it does not remove existing adapters.

Activation and safe upgrades

Choose --agents-position append or prepend. Setup adds or replaces exactly one marked block linking the fixed protocol and bootstrap location. It preserves unrelated instruction bytes, UTF-8 BOMs, and the original newline style, with minimal separating whitespace. A missing root file gets a small scaffold plus the block. --agents-position skip leaves an existing file unchanged (including any existing block), or creates only a neutral root marker. It is not uninstall.

The block is a loading instruction, not a permissions override or guaranteed runtime hook invocation. Review/approve native hooks, then start a new session or reload instructions through the runtime. Existing sessions may cache previous instructions. The installer never bypasses trust or edits CLAUDE.md or scoped component files. OpenCode's instruction-triggered bootstrap still has the documented limitations.

Reinstalling without profile flags preserves identity, dispositions, self-model, and experience history. Repeating identical explicit profile choices is a no-op. Changing an existing profile requires --replace-profiles or explicit wizard approval; only selected profiles are replaced, with exact backups. The entire selected profile, including any learned content, is replaced: review the preview. Self-model and accepted history are never reset. Placement and adapter selections are remembered locally for later runs.

Changed existing files have exact backups; unchanged files are not rewritten. Malformed block markers, invalid profiles/configuration, conflicting edits, and oversized startup context stop installation visibly. Publication is atomic per file, not an all-or-nothing transaction. See the installer guide for recovery and the distinction between preflight and live verification.

Installed structure

existing-project/
├── AGENTS.md                              # Managed activation block or explicit skip
├── .codex/hooks.json                      # Merged when selected; review/trust
├── .claude/settings.local.json            # Merged when selected
├── opencode.json                          # Merged when selected
└── .agent-personality/
    ├── PERSONALITY.md                     # Fixed protocol
    ├── LOCATION.md                        # Generated root/bootstrap location
    ├── REFERENCE.md                       # Record schema and workflow
    ├── tools/
    │   ├── mettle.py                      # Core helper
    │   └── mettle_installer.py            # Guided setup and profile constructors
    ├── .gitignore                         # Excludes mutable state
    └── state/
        ├── installation.json             # Local placement/adapter choices
        ├── personality/
        │   ├── identity.md
        │   ├── dispositions.md
        │   └── self-model.md
        ├── memory/
        │   ├── INDEX.md
        │   ├── vocabulary.md
        │   ├── lessons/<domain>/<lesson-id>/
        │   │   ├── current.md
        │   │   └── revisions/0001.md
        │   ├── episodes/<year>/<month>/
        │   ├── reviews/<year>/<month>/
        │   └── reconciliations/<year>/<month>/
        └── sessions/

Subdirectories and nested lesson domains are supported. The installed helper anchors all managed paths to its fixed repository root, never a nearer component AGENTS.md. After moving a target or interpreter, run the installed helper with install --configure-only --root NEW_ROOT --non-interactive; add --python-executable when needed. This refreshes integration files and the chosen activation block without replacing profiles or upgrading deployed code. To update the code/protocol, run a normal installation from the new source checkout.

An existing opencode.jsonc is not rewritten. Exclude OpenCode from installation and use adapter --runtime opencode to obtain a manual-merge fragment; see the integration guide. No independent skills/ subsystem is installed: procedures remain scoped lessons and tools/ is maintained code.

How the loop works

1. Retrieve for a decision

Search using the intended action, component, and likely failure mode. Repeat when a newly discovered subtask changes what matters—not before every tool call.

PowerShell, using the installed paths from Quick start:

& $Python -X utf8 $Mettle search generated bindings
& $Python -X utf8 $Mettle search permissions --scope authorization
& $Python -X utf8 $Mettle show L-example

macOS/Linux:

python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py search generated bindings
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py search permissions --scope authorization
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py show L-example

Search returns candidate IDs, current revisions, status, scope, and any pending counterexample reviews. Read the full record before applying it. A keyword match is not proof of relevance, a score is not confidence, and no applicable lesson is a valid result. Archived or superseded wording is not an active rule.

Preserve distinctive source terms in lesson metadata so useful abstractions stay searchable. A term inferred from prior context can help discover a candidate, but cannot expand the current request. Check current authorization before any side effect; a retrieved procedure is not permission to commit, push, or deploy.

2. Observe and propose an adjustment

An episode records observable actions, outcomes, sources, and tentative interpretations. Its context can be a current request or an opportunity under a standing goal; it need not invent a human-issued task. A lesson turns that evidence into a conditional practice:

When modifying generated interfaces in component X, change the source schema and regenerate, unless the component explicitly uses hand-maintained bindings.

Keep scope, exceptions, expected benefit, and a later review plan. Do not turn one event into a global self-description such as “I am careless.” Successes can also yield practices worth preserving.

3. Review a later application

A review names an exact lesson revision and the episodes documenting its later application. It can support the practice, report a counterexample, record misapplication, or leave the result uncertain. Not applying an inapplicable lesson can be a correct decision. Record why the candidate fit or was rejected, what actually changed in the agent's action, and the observable outcome. Do not claim a causal improvement from a single successful result or a fluent explanation. The decision-to-review trace uses the existing schema; no new record kind is required.

4. Reconcile without erasing history

Use explicit ADD, REVISE, LINK_EVIDENCE, MERGE, MARK_CONTESTED, or RETIRE decisions. Publish a new lesson revision, retaining evidence references and contradictory cases. Old revisions remain immutable. current.md and indexes are generated views; reindex --repair can rebuild them after an interrupted publication. A separate reconciliation pass can be performed by the same agent; it is a role separation, not a requirement for another model. Retain the evidence and prior wording behind self-model changes too. A replaceable summary or Git baseline is not a substitute for explicit history.

Recovery from a bad generalization uses the existing REVISE/publication path: recheck the earlier practice, retain intervening evidence, publish a new current revision, and arrange a later review. It is not reindex --repair, which repairs derived files rather than beliefs. See the recovery procedure.

There is no background LLM worker. The participating agent follows the protocol, prepares drafts, and invokes the helper. Human operators can use the same commands. The validator checks structure and provenance links, not whether a reflection is psychologically or causally true.

Record commands

Records use JSON metadata between --- delimiters followed by Markdown. The helper intentionally does not require a YAML library or accept arbitrary YAML.

In PowerShell 5.1 or 7, with $Python and $Mettle set as above:

& $Python -X utf8 $Mettle template episode --output episode-draft.md
# Edit the UTF-8 draft: replace every TODO with actual observations and limits.
& $Python -X utf8 $Mettle publish episode-draft.md
& $Python -X utf8 $Mettle template lesson --output lesson-draft.md
# Supply its originating episode ID, scope, practice, exceptions, and review plan.
& $Python -X utf8 $Mettle publish lesson-draft.md --expected-revision 0
& $Python -X utf8 $Mettle check

--output writes UTF-8 without a BOM, with LF line endings, and refuses existing files. The stdout form remains available. Use --output instead of > or Out-File to avoid PowerShell 5.1's UTF-16 redirection default. User-edited UTF-8 with a BOM and CRLF is accepted; arbitrary legacy encodings are not guessed. show ID --output revision-draft.md also creates a safe draft for a later revision.

macOS/Linux examples (or adapt the argv prefix in installed LOCATION.md):

# Generate a draft, replace all placeholders, then publish it.
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py template episode --output /tmp/episode.md
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py publish /tmp/episode.md

# New lessons require the expected prior revision, zero for a new ID.
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py template lesson --output /tmp/lesson.md
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py publish /tmp/lesson.md --expected-revision 0

# After publishing a review and reconciliation, publish a revised lesson.
python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py publish /tmp/lesson-v2.md --expected-revision 1

python3 -X utf8 /path/to/project/.agent-personality/tools/mettle.py check

See the record specification for required fields, the full publication sequence, recovery, and semantic checks. Run the isolated, synthetic worked example with:

python3 -X utf8 examples/walkthrough.py

The example uses a temporary project and is never seeded into a real agent's memory. Example success is a storage/protocol demonstration, not a learning experiment.

Boundaries and known limitations

Memory is evidence, not authority. It cannot grant permissions, override project requirements, or authorize self-modification. Native hooks may inject text at a high instruction priority; mutable profile data is explicitly labelled, but that label is not a prompt-injection security boundary.

Use one authoritative writer. The helper serializes its own operations with a filesystem lock, but cannot prevent direct file edits or resolve two independent concurrent personalities sharing this store. Bootstrap logs record emission and hashes, not delivery or obedience. A hook that never runs cannot report its own absence.

Windows support initially targets local NTFS. Network shares, other Windows filesystems, and synchronized folders are untested and unsupported for this pilot. Symlinks, junctions, reparse points, traversal, and Windows filename aliases are rejected in managed Windows paths. New IDs cannot differ only by case. Windows rejects ambiguous or nonportable archives visibly; existing POSIX-only histories remain readable on POSIX and are never silently renamed. Immutable publication still uses a fully written temporary file plus os.link; generated views use os.replace. Unsupported hard links or filesystem errors stop the operation, with no overwrite fallback. See recovery and storage boundaries.

Codex Windows hooks can use the session's PowerShell or fall back to CMD. The generated command supports both through the built-in Windows PowerShell launcher, with encoded arguments and literal executable paths; % and ! are supported. Claude uses direct executable-plus-args hooks. OpenCode's Windows bootstrap uses an explicitly selected PowerShell or CMD shell; existing shell settings are preserved or an unsupported choice is reported before writing. OpenCode's CMD form still rejects paths containing % or ! during preflight.

State stays local but is sent to the configured model provider when an agent reads it. Do not store secrets or unnecessary personal information. .gitignore is not encryption, access control, synchronization, or backup. Review generated absolute-path configurations and backups before committing. See security and privacy.

Lexical retrieval can miss paraphrases. Retrieval validates the local record graph and is linear in the memory archive; it does not scan the source tree. There is no measured large-memory performance guarantee. Startup context has an explicit character budget and fails visibly rather than silently truncating a personality. Character counts are not token or billing measurements.

This is not a claim of consciousness, an MBTI personality implementation, or a proven remedy for model drift. Different models can use the same state differently; record model/runtime provenance and evaluate changes.

Evaluation and development

PowerShell, using a Python 3.11+ executable:

& $Python -X utf8 -m unittest discover -s tests -v
& $Python -X utf8 examples/walkthrough.py
& $Python -X utf8 -m py_compile mettle.py examples/walkthrough.py

macOS/Linux:

python3 -X utf8 -m unittest discover -s tests -v
python3 -X utf8 examples/walkthrough.py
python3 -X utf8 -m py_compile mettle.py examples/walkthrough.py

The offline suite checks installation and upgrade safety, relocated/nested-root resolution, UTF-8 pipes/files, generated hook launches, immutable records, references, revision conflicts, counterevidence, recovery, junction rejection, and fresh-process persistence. Windows tests execute CMD, available PowerShell 5.1/7 shells, and direct process launches with unusual paths. Symlink tests first attempt creation and report unavailable privileges as a skip. CI retains Linux and runs Windows with Python 3.11, 3.12, and 3.13. Configuring that matrix is not evidence its jobs passed. Synthetic archives are not hundreds of real conversations; see integration verification for the distinction between process tests and live runtime loading.

The evaluation plan separates storage, loading, retrieval, application, and correctability. It includes negative transfer, task-order sensitivity, unseen applications, model changes, and total token/latency cost including reflection and maintenance—not just fewer action steps. Control other memory sources so runtime-native memories, imported skills, or earlier context do not silently confound attribution. The synthetic behavioral-review fixture and its tests check record handling, not whether an LLM learned or obeyed a rule.

Related projects and research

This map records the work discussed while designing Agentic Mettle. Links point to papers, official projects, or runtime documentation. Inclusion is not an endorsement, a dependency, or a claim that results transfer to this protocol. No benchmark results from these systems are presented as Agentic Mettle results. Research and runtime documentation were reviewed on 2026-09-30; preprints and software interfaces can change.

Experience-to-strategy learning and reconciliation

Work	Relevant contribution	Boundary for this project
ReasoningBank · code	Distills strategies from successful and failed attempts and retrieves them for subsequent tasks.	Task-performance evidence, not persistent identity. Its released memory loop is not our full revision/counterevidence model.
Reflexion	Stores feedback-derived verbal reflections to improve later attempts without weight updates.	Repeated-attempt learning does not establish development across hundreds of independent conversations.
ExpeL · code	Extracts and revises insights through explicit agreement, addition, editing, and removal operations.	Inspires explicit reconciliation; Mettle retires or supersedes evidence-backed records rather than silently erasing them.
Agent Workflow Memory · code	Abstracts reusable workflows from experience, including recurring subtasks.	Inspires action-level retrieval; a workflow engine is outside V1.
Dynamic Cheatsheet · code	Maintains evolving strategies and reusable methods across sequential problems.	Recurring benchmark families and model-dependent effects are not general lifetime validation.
Agentic Context Engineering — ACE	Separates generation, reflection, and curation; uses localized playbook updates.	Inspires stable records and incremental changes, not automatic rewriting of project instructions.
MemRL	Combines semantic relevance with feedback-derived utility for memory retrieval.	Relevance and usefulness differ. V1 records applications but does not implement reinforcement learning or utility optimization.
Evo-Memory / ReMem	Studies sequential experience reuse and active refinement of an evolving memory.	Informs ordering, failure-contamination, and distribution-shift tests.

Persistent agents, self-models, and memory architectures

Work	Why it is relevant	Important distinction
Generative Agents	Experience streams, reflection, planning, and ongoing social behavior.	Short simulated social behavior is not indefinite autobiographical stability.
MemGPT / Letta	Explicit state and memory management beyond a single context window.	Persistence infrastructure does not itself validate a coherent self-model.
MemoryBank	Long-term conversational memory and adaptation to users.	Learning about a user's preferences is different from developing the agent's own identity.
Voyager	Acquires and reuses executable skills through interaction and feedback.	Demonstrates procedural accumulation in Minecraft, not a runtime-neutral personality protocol.
Hindsight	Retain, recall, and reflect mechanisms with distinctions between facts and opinions.	Memory QA and opinion machinery are not longitudinal behavioral validation.
Sophia	Explicit self-model, narrative memory, reflection, and goal generation.	A close architectural comparison with exploratory pilot evidence.
MIRROR	Reflective context and continuing internal narrative for reasoning/constraint maintenance.	Its narrow evaluation should not be mistaken for hundreds of continuing conversations. Mettle records observable evidence, not hidden reasoning.
PEPA	Episodic experience and reflection can change embodied-agent goals and priorities.	Short embodied experiments are not a general conversational identity benchmark.
Vigil	Deployed on-call support with review-driven knowledge maintenance.	Shared support knowledge at deployment scale differs from one individual's autobiographical development.

Evaluation, self-correction, and persona persistence

Work	Relevance
LongMemEval	Tests long-history extraction, updates, temporal reasoning, and abstention. Useful for memory, but history-question answering is not behavior developing through that history.
Persistent Personas?	Examines persona fidelity during extended task-oriented interaction; motivates testing more than initial personality prompting.
InCharacter	Personality-fidelity assessment through psychological interviews; supplementary rather than sufficient behavioral evaluation.
PersonaGym	Evaluates persona agents in relevant situations, including actions and consistency.
Prompting Against Persona Drift	Studies reminder and corrective interventions in a narrow simulation; preliminary, not lifetime reliability evidence.
Large Language Models Cannot Self-Correct Reasoning Yet	Warns against equating unsupported self-critique with reliable correction in the studied settings.
ProCo: Key Condition Verification	Examines an explicit verification method; distinguishes targeted checks from an unrestricted request to reflect more.
A psychometric framework for evaluating and shaping personality traits in LLMs	Supports investigating measurable behavioral tendencies without assuming human psychological mechanisms or indefinite stability.
LLM Agents Grounded in Self-Reports	Models individuals from detailed evidence; representing an existing person differs from an agent developing through its own experience.
Persona Vectors / The Assistant Axis	Internal-activation approaches to monitoring or steering behavior. Architecturally different from a portable external state protocol.

MBTI work considered, not adopted

MBTI is not part of V1. The earlier discussion included Do LLMs Possess a Personality?, Machine Mindset, Open Models, Closed Minds?, Psychologically Enhanced AI Agents / MBTI-in-Thoughts, and Do Personality-Tuned LLMs Make Better Social Agents?. These concern measuring or inducing personality-labelled behavior. Questionnaire alignment, useful operational behavior, and long-term continuity remain distinct claims; Mettle uses explicit, revisable dispositions rather than four-letter types.

Context management and runtime foundations

Codex's agent loop, Responses API compaction, and Anthropic's context engineering discussion inform the distinction between a replaceable working context and durable evidence. Compaction is not, by itself, reflective learning.

The adapters follow Codex hooks, Claude Code hooks, Claude instruction discovery, OpenCode rules, and OpenCode plugins. See integration details for differences and limitations.

License

MIT. Research references retain their authors' rights and licenses. This initial implementation is original code inspired by published ideas; it contains no vendored research implementation and has no affiliation with the referenced projects.