immortal-skill: a Python framework for distilling chat logs into persona files

The gap immortal-skill is aiming at

The README draws a line between two things that are often conflated. One is dumping chat history into a vector store and retrieving nearest neighbours at query time. The other is producing a structured description of how a person thinks, speaks and decides, in a form an agent can load as a persona. The project's own phrasing is that it is not about pouring chat logs into a vector database but about understanding how a person thinks, talks and makes decisions. That distinction matters because retrieval and persona modelling fail in different ways. A vector index over messages will surface the sentence someone actually said, which is fine for lookup and useless for generating a reply in their voice on a topic they never discussed. A persona file is the opposite: weaker on exact recall, stronger on consistent behaviour. The intended audience is anyone holding a chat export they care about (a departing colleague, a retired mentor, a deceased relative, a public figure whose talks and interviews are already public) and who wants something more portable than an embedding index. The README is explicit that the output is meant to be loaded by AI, not read by humans.

Four-dimensional distillation and what the persona file contains

The framework describes its output as four-dimensional, and the README's own summary of the dimensions is how someone works, how they speak, what they have lived through, and who they are. The persona table applies that same breakdown per subject type: for a colleague the focus is workflow plus communication style, for a mentor it is teaching method plus life wisdom, for a relative it is family memory plus speech habits. The repository also states alignment with the OpenClaw Soul Spec and the AgentSkills standard, and the README lists seven role templates. None of the template names or their field definitions appear in the supplied material, so the concrete schema is something you would have to read out of SKILL.md before committing to it. The architecture implied by the repository layout is prompt-first rather than library-first: SKILL.md at the repository root is described as the general distillation engine, FOR_AI.md holds four copy-pasteable instruction blocks for an agent, and the README tells the agent to set the working directory to the repository root, read FOR_AI.md first, then open the SKILL.md matching the user's intent and execute it, invoking Python commands from the repository root when a script is needed. So the data flow is: you supply an export, the agent reads the skill document, follows its extraction instructions, and writes a persona artifact. The Python in the repository appears to be the script layer the skill calls into, not an importable library you drive from your own code.

Getting it running: the commands the README actually gives

There is no install section in the supplied README. No pip command, no requirements file, no CLI entry point, no config keys. The closest thing to a run instruction is the block the README offers for handing the whole repository to an agent: set the working directory to the repository root, read FOR_AI.md first, then open the SKILL.md corresponding to the user's intent and execute it, and when scripts are required use the Python commands written in FOR_AI.md relative to the repository root. Two constraints are stated elsewhere. The badge declares Python 3.9 or later. The licence is MIT, and the LICENSE file is at the repository root. That is the entire operational surface described in the material I have. For a project whose pitch is a one-line instruction that teaches your AI to distil, the absence of a documented install path is a real gap, and it is the first thing to resolve before you plan around this. The practical reading is that the intended usage is conversational: you point an agent at the repository and let FOR_AI.md drive it, rather than installing a package and calling functions.

The consent problem is designed in, and it is still the weak point

The README's ethics column is unusually direct for a project of this kind. Self-distillation is stated as your data, your call. A colleague's distillation is scoped to internal team use. A mentor requires the person's authorisation. A relative requires family consent. A former partner requires positive memories only and strict de-identification. A public figure is handled through the separate steamer-skill repository, which frames public talks, interviews and blog posts as material the audience already paid for. That is a more careful position than most persona projects take, and it is worth noting that the ethics column is a statement of intent, not an enforcement mechanism. Nothing in the supplied material describes a consent check, an access control, or a provenance field in the output. The enforcement layer is a sibling repository, distill-protocol-skill, which the README describes as separating authorisation into six questions covering whether distillation is allowed, whether the output can be used commercially, and whether the resulting persona may stand in for the person at work. The README itself calls the nickname a joke with quotation marks, and says the underlying document is serious. Read that as an accurate self-assessment: the protocol is a document you adopt voluntarily, and it does nothing on its own.

Where it breaks: exports, drift and the wrong use case

The README claims support for more than twelve platforms including WeChat, Feishu, iMessage and Telegram. It does not describe a parser per platform, nor does it name the export format it expects. That is the failure mode most likely to bite first. Chat exports differ in timestamp granularity, sender labelling, handling of images and voice notes, and whether quoted replies are inlined or referenced. A persona built from a poorly parsed export will inherit those artefacts, and the four-dimensional structure will not detect the problem, because the extraction step has no ground truth to check against. A second limitation is drift: a persona distilled from logs ending at a particular date encodes that person at that date, and nothing in the material describes a refresh or re-distillation path. The third is scope. This is the wrong tool if what you actually want is searchable recall over a message archive, because a persona file deliberately compresses away the exact wording of individual messages in favour of general patterns. It is also the wrong tool for any subject whose messages you hold but whose consent you do not, whatever the technical feasibility.

What it is not: the difference from RAG over chat history

The obvious alternative is the standard retrieval pipeline: chunk the export, embed it, store it, retrieve at query time, and let the model answer from retrieved passages. The difference in approach is where the compression happens. Retrieval keeps every message and compresses at query time, so the model sees real text and can cite it, but it has no model of the person and will produce generic phrasing wrapped around their words. immortal-skill compresses at ingest time into a structured persona, so the model gets a description of how the person argues and what they care about, and can generate on topics absent from the logs, at the cost of losing the ability to quote accurately. The two are complementary rather than competing, and a serious implementation would probably run both: a retrieval layer for recall and a persona file for voice. The second alternative named in the README is the steamer-skill repository, which is not a different implementation but a different target. It extracts cognitive frameworks from public material (talks, interviews, books) so the output acts as an advisor, rather than reconstructing a specific individual's manner. If your goal is a thinking partner rather than a likeness, that is the branch to look at.

Maintenance cost and what the MIT licence does not settle

The repository is not archived, and the last push recorded is 2026-04-15. No releases were retrieved, which means there is no versioned artifact to pin and no changelog to read for breaking changes. In practice you would be tracking the main branch, and since the framework is prompt-driven, a change to SKILL.md can alter output behaviour without any code change or version bump. That is a maintenance property worth naming: with an instruction-driven pipeline, the diff you need to review is prose. On licensing, the code is MIT, which is permissive and places few conditions on reuse. It does not govern the data you feed in. Chat logs contain other people's messages, and the MIT grant on this repository says nothing about your right to process them, nor about what the resulting persona file inherits. The README's own note on the pre-built persona plaza, that the content is for study and methodological practice and does not represent the person's position or authorisation, is the project flagging exactly this boundary. Whether a distilled persona of a real person creates obligations under your jurisdiction's personality or data protection rules is a question for a lawyer, not for this review.

Editorial conclusion

Adopt immortal-skill if you already have a clean export of your own chat history and you want a structured, spec-aligned persona file rather than a raw vector index of messages. Do not adopt it if you need a supported ingestion path for a platform whose export format is undocumented, or if the subject of the distillation has not consented. Before writing any code against it, verify three things: what SKILL.md actually instructs the agent to do, which of the seven role templates maps to your use case, and whether your export contains third-party messages you have no right to process.

Official sources

1. agenmod/immortal-skill on GitHub
2. Issues
3. License: MIT
4. Project website
5. README