Motion Memory: A Local Small-Model Memory Plugin for AI Coding Assistants (Initial Release)

    Motion Memory is a local memory-management plugin for highly customizable coding-tool runtime environments, designed to give AI coding assistants persistent, long-term memory that keeps improving with use. This article explains why extraction and summarization are handled by local 7B–9B small models instead of cloud LLMs, presents a four-layer memory structure (session log, candidate memory, formal memory, and topic summary) with full traceability, and details the entry schema, five memory types, write strategies, periodic summarization, context injection, conflict handling, and forgetting. It also covers plugin-based integration and practical advice. Readers get a complete blueprint for building an auditable, local-first memory system that "gets to know you better over time" while controlling cost and protecting privacy.

    Introduction: Helping AI Coding Assistants “Understand You Better Over Time”

    Have you ever had this experience with an AI coding assistant: yesterday you agreed with it that “every API must declare pagination parameters explicitly,” but in a fresh session today it goes back to implicit defaults; the build-cache and path-encoding issues you hit last week resurface this week? The reason is straightforward: large models are stateless, and the only world they can see is what’s inside the current context window. Once a session ends, the conclusions, preferences, and lessons distilled from those discussions simply evaporate.

    As a result, developers have to re-explain the same background over and over. This wastes tokens and patience. Solving it requires “long-term memory” that lives independently of any single session, accumulates continuously, and gets to know you better over time. This article takes Motion Memory’s initial release as a case study: a local memory-management plugin built for highly customizable coding-tool runtime environments (referred to collectively as “the runtime environment” below). Let’s look at its design philosophy and engineering practices.

    Its positioning can be summarized in three points:

    • Selective content: only genuinely long-term-worthy material is retained — conclusions, preferences, project constraints, process methods, and lessons from mistakes.
    • Steady maintenance: real-time tracking during conversations and periodic consolidated summarization alternate, keeping memory “fresh and trustworthy.”
    • Fully local: memory documents are stored locally and the supporting model runs locally too, so all content is controllable, inspectable, editable, and deletable.

    1.1 What’s Worth Retaining

    Not every conversation deserves a place in long-term memory. Using “will it be reused in the future?” as the criterion, information falls into three categories:

    Category Typical content Store in memory? Reason
    Long-term constraints Tech stack versions, coding standards, directory conventions, prohibitions Yes, highest priority Affects almost every future output
    Stage conclusions API field-naming schemes, error-code conventions, deployment processes Yes, with a validity period Referenced repeatedly within the project
    Process information Intermediate variables from a debug session, temporary logs, one-off discussions No, keep in session logs Low reuse value, high noise

    The “process information” in the table doesn’t enter the memory bank, but it is retained in session logs as a source for traceability.

    1.2 Two Rhythms of Memory Maintenance

    Memory maintenance mainly runs on two rhythms:

    • Conversation tracking handles timeliness: it identifies worth-remembering content during a session and stages it as a candidate entry first, so nothing is missed afterward.
    • Periodic summarization handles accuracy: during idle time, a local model batch-distills the content, then deduplicates, merges, and resolves conflicts to produce formal memory.

    The former pursues timeliness, the latter quality. Combined, memory won’t “remember a lot” while “remembering messily.”

    2. Why Hand Extraction and Summarization to a Local Small Model

    A natural way to build long-term memory is to call a general-purpose LLM and ask it to “read today’s conversation and summarize it for me.” But for this kind of memory-management plugin, that approach isn’t cost-effective.

    2.1 The Core Cost Problem: The Context Changes Every Round

    Mainstream LLM services commonly offer prompt caching: when a request’s prompt prefix matches that of a previous request, the matched tokens are usually billed at a lower price. The typical workflow of a memory-management plugin is “assemble a context + have the model process it”: every request concatenates the current memory entries, the session segments to process, and the instruction and output-format requirements into an entirely new prompt.

    Memory entries are added or revised as conversations progress, and the content to process differs in each batch, so the prompt prefix is almost never identical across two requests. This drives the cache-hit rate close to zero, and nearly every call pays for the full context. On token-billed services, this overhead keeps growing as memory scales.

    2.2 The Division of Compute

    Since the problem is “repeatedly carrying context to call a remote service,” the most direct fix is to move those calls locally. Local small models in the 7B–9B range can be loaded through common local inference tools and are usually sufficient for these structured, lightweight tasks:

    • Classification: deciding whether a conversation contains conclusions, constraints, or lessons;
    • Extraction: pulling entries out of the source text into a fixed JSON structure;
    • Summarization: merging multiple candidates into a single self-contained memory;
    • Judgment: identifying similar entries and old-vs-new conflicts.

    These tasks need strong “understand and follow the format” ability but only modest demands on breadth of knowledge and deep reasoning. On an ordinary discrete-GPU workstation or a well-equipped laptop, batch-processing a session usually takes only a few seconds to tens of seconds, and it can be scheduled entirely during idle periods. The compute allocation looks roughly like this:

    Task type Suggested location Reason
    Code generation, complex refactoring, hard problem localization Cloud general-purpose LLMs Needs strong reasoning and knowledge coverage
    Memory extraction, categorization, summarization, conflict judgment Local small models Light tasks, frequent calls, and private session content
    Deduplication, similarity comparison, validity checks Local rules and algorithms Deterministic and nearly zero cost

    This forms a clear division of labor: cloud models handle “hard and important” reasoning, while local models and local compute handle “frequent and repetitive” memory maintenance.

    2.3 Four Lessons on Model Selection

    1. No need to chase large models: the main flow of a memory plugin is structured output, which a well instruction-following local small model can handle. When more capability is truly needed, model routing configured in the runtime environment can assign different models to different stages.
    2. Value instruction tuning: prefer model versions that have been instruction-tuned and handle JSON output well. Such models reliably produce valid structures even at higher temperatures.
    3. Keep temperature low: structured extraction tasks use a low temperature parameter, which significantly reduces format errors and content fabrication.
    4. Leave a fallback path: even with a paid model, “rule-based extraction + manual confirmation” should guarantee the main flow stays usable, so memory maintenance doesn’t break entirely when the model service is unavailable.

    3. A Four-Layer Memory Structure: Traceable All the Way Down

    The core design of Motion Memory is to split memory into four layers. Each layer answers only one question, and upper layers reference lower ones, forming a complete evidence chain.

    3.1 Layer 1: Session Log (Raw Logs)

    The session-log layer stores raw records of interactions with the runtime environment — user messages, assistant replies, and tool-call results — tagged with session IDs, message indices, and timestamps. This layer is read-only; no organizing process may modify the original text. It plays the role of a “negative”: if any later organizing step goes wrong, you can always return here and re-distill.

    3.2 Layer 2: Candidate Memory (Memory Sketches)

    The candidate layer holds the “memory sketches” extracted by conversation tracking and periodic summarization. Each candidate points back to a specific message location in the raw records via a source field. The candidate layer has three characteristics:

    • No direct impact on output: candidate content is never injected directly into the model’s context;
    • Carries a confidence score: given per entry;
    • Can be discarded: duplicate or erroneous candidates can be safely deleted without affecting other layers.

    With this layer, memory management achieves “record first, confirm later,” preventing noise from directly contaminating formal memory.

    3.3 Layer 3: Formal Memory (Memory Bank)

    The formal layer stores only confirmed structured entries. It is the main product of periodic summarization and the primary source for context injection. Entries follow a unified schema, which makes version control and incremental retrieval easy, as in Code 1:

    1. # Memory entry example (illustrative; fields can be trimmed to the runtime's needs)
    2. id: mem-0007
    3. type: constraint # conclusion / preference / constraint / process / lesson
    4. text: External APIs must declare pagination parameters explicitly; implicit defaults are forbidden.
    5. scope: project # project: active only in the current project; global: shared across projects
    6. source: # Provenance: points back to the candidate entry and raw message
    7. candidate: cand-0031
    8. session: sess-2f8a
    9. msg_index: 42
    10. status: confirmed # proposed / confirmed / superseded / expired
    11. confidence: 0.92
    12. supersedes: null # ID of the old entry superseded by this one
    13. expires_at: null # Expiry time; empty means valid long-term

    3.4 Layer 4: Topic Summary (Memory Index)

    The topic-summary layer is a “table of contents” on top of Layer 3. It compresses multiple formal memories into short summaries by topic or time window — for example, “Payments module: follows the unified error-code convention, covering 3 agreements.” At the start of a session, the assistant reads the summaries first to quickly build a global understanding; when details are needed, it drills down via references to specific entries, and if necessary back to the raw records. This both controls the size of injected context and preserves fine-grained “look it up anytime” detail.

    3.5 Three Benefits of Layered Traceability

    The four layers are linked through ID references along the path: topic summary → formal entry → candidate entry → raw message. This design brings three benefits:

    • Auditable: any memory can answer “where did it come from, and which exact sentence supports it”;
    • Rollback-able: when formal memory goes wrong, you can fall back to the candidate layer to reconfirm, or re-distill directly from the raw records;
    • Incremental: new content only needs appending candidates — no need to rewrite the whole memory document.

    4. The Entry Schema and Write Strategy

    4.1 Field Design Principles

    The entry schema follows a “minimal but sufficient” principle. Each field means:

    • id: a globally unique identifier, commonly in the form “type prefix + time + sequence”;
    • type: the entry type. The type determines injection priority and the conflict-handling strategy;
    • text: an atomic statement. One entry states only one thing and is understandable on its own, out of context;
    • scope: the scope. Project-level memory is active only in the corresponding project; global-level memory is reused across projects;
    • source: a provenance reference pointing to the candidate entry, session, and message index;
    • status: the entry status. Only confirmed entries get injected;
    • supersedes / expires_at: handling old-vs-new replacement and validity respectively.

    4.2 The Five Memory Types and Their Traits

    Type Content example Main source Conflict-handling trait
    conclusion “Error codes use a unified six-digit segmented scheme” Discussion or plan confirmation New conclusion replaces old
    preference “Code comments in Chinese, explaining why rather than what” Explicit user expression Latest user expression wins
    constraint “No implicit defaults”; “Dependencies pinned to exact versions” Project requirements On conflict, raise an error and let a human decide
    process “Before release, run static checks, unit tests, and build in order” Process mapping Versioned and retained, selected by stage
    lesson “Build cache occasionally fails in this environment; clear it and retry” Mistakes and troubleshooting Weighted by time decay, gradually fades out

    4.3 Three Write Strategies

    1. Atomic: one memory expresses a single fact; avoid compound “both… and…” statements, otherwise it’s hard to retrieve and replace independently.
    2. Self-contained: the wording must not depend on the conversation context. For example, don’t write “as above, adjustment is needed”; instead spell out what is being adjusted and how.
    3. Bounded: explicitly mark the effective range, the applicable project, and the expiry time, so “expired memory” doesn’t interfere with new sessions over the long term.

    5. Periodic Summarization: From Conversation Flow to Structured Memory

    Periodic summarization distills the conversation flow into structured memory and is best split into six steps:

    1. Trigger: start when a session ends, during idle periods, or when a preset cycle is reached. Right after a session ends, the context is freshest and closest to the user’s true intent.
    2. Select and batch: read the session records within an agreed time window, slice them by session, and keep each batch within a length the model can reliably process.
    3. Extract: put the candidate schema and strict requirements into the prompt, and have the local model output a JSON array, as in Code 2:
    1. [
    2. {
    3. "type": "lesson",
    4. "text": "In this project's build environment, dependency caches occasionally fail and cause missing artifacts; clearing the cache and rebuilding restores it.",
    5. "scope": "project",
    6. "evidence": "Missing artifacts appeared twice in a row and returned to normal after clearing the cache",
    7. "confidence": 0.8
    8. }
    9. ]
    1. Validate: run programmatic validation first — whether the JSON is valid, whether required fields are complete, whether the type value is legal, and whether confidence meets the threshold. Entries that fail are returned to the candidate layer to await reprocessing in the next round.
    2. Normalize: compare semantically similar entries for similarity (text vectors or character-level similarity both work). Merge duplicates, flag conflicts, then hand them to a human for confirmation.
    3. Persist: write the processed entries into formal memory and update the topic summary accordingly, so the memory bank stays usable.

    The whole process should be idempotent. A processing marker such as “session ID + message index + content hash” lets repeated periodic-summarization runs automatically skip already-processed segments, avoiding a pile-up of duplicate entries.

    6. Context Injection: Making the Assistant “Recall” What It Should

    Memory is valuable only when it’s correctly retrieved. Context injection answers three questions: when to inject, what to inject, and how much.

    • Injection timing: prefer injecting once at session start or project switch so the assistant builds a global understanding; then retrieve and supplement on demand by current topic during the conversation, avoiding a full injection every turn.
    • Ordering strategy: first set priority by type — constraints and preferences ahead of conclusions and processes — then rank by similarity, freshness, and confidence.
    • Size control: set a token budget cap; entries over budget are left for on-demand retrieval. When the budget allows, inject the topic summary first, then add the most relevant handful of details.

    An example is Code 3 (pseudocode):

    1. TYPE_PRIORITY = {"constraint": 0, "preference": 1, "conclusion": 2, "process": 3, "lesson": 4}
    2. def build_memory_context(project, query, budget):
    3. items = [m for m in load_confirmed(project) if not is_expired(m)]
    4. # Constraints and preferences are always injected; the rest are selected by relevance to the current topic
    5. matched = [m for m in items if m.type in ("constraint", "preference")
    6. or relevance(m, query) >= THRESHOLD]
    7. matched.sort(key=lambda m: (TYPE_PRIORITY[m.type], -freshness(m)))
    8. picked, used = [], 0
    9. for m in matched:
    10. cost = estimate_tokens(m)
    11. if used + cost > budget:
    12. break
    13. picked.append(render(m))
    14. used += cost
    15. return "\n".join(picked)

    7. Conflict Handling and Forgetting

    As memory accumulates over time, the hard part isn’t “recording it” but “remembering which one.” Conflicts fall into three main cases:

    • Preference change: the user first says “I prefer concise code,” then “the team requires full comments.” Apply the take-the-newer rule by time, mark the old entry as superseded, and keep the reference for traceability.
    • Fact update: when dependency versions, API fields, or directory structures change, the old conclusion is replaced by the new one. When needed, you can re-distill from the raw records.
    • Wording differences: two entries are semantically identical but phrased differently; merge them into one and keep the source with the most references.

    Beyond conflicts, forgetting matters just as much. Lesson-type memories can have their weight decayed over time, and once an entry’s expires_at is reached it automatically moves to the expired state and no longer participates in injection, though it stays in the memory bank for reference. Forgetting isn’t deleting history — it’s keeping the current context clean.

    It’s worth stressing: when constraint-type memories conflict directly, the system should not silently “adopt the newer one” but should prompt the user to decide. A silently overwritten hard project-level constraint can throw an entire round of output off-spec.

    8. Configuration and Integration: Fitting In as a Plugin

    Motion Memory uses a “core plugin + settings UI” combination, leveraging the runtime environment’s high customizability for integration. The core idea breaks into four steps:

    1. Place the plugin files: put the memory core plugin (a single-file plugin written in JavaScript), the settings-UI plugin (split into a frontend and a backend service, with a package descriptor), and the pure-function module directory into the runtime environment’s plugin directory. The pure-function modules don’t depend on a specific runtime, making them easy to test and reuse on their own.
    2. Map UI dependencies: some runtime environments load UI-type plugins by npm package structure, so the plugin directory and the same-named entry in the dependency directory must point to the same file. On Windows this can be done with a directory junction; on Unix-like systems, use a symbolic link. You can also copy the file directly, but be careful to keep it in sync on later updates.
    3. Register and enable: register the plugin entries in the runtime environment’s config file (such as the patch config of the profile), for example:
    1. # cordis.patch.yml (illustrative)
    2. - insert:
    3. - id: motion-memory
    4. name: ./plugins/motion-memory.js
    5. - id: mm-settings
    6. name: mm-settings
    1. Restart to take effect: after restarting the runtime environment, the memory commands (the memory_* series) and the settings UI load automatically with the plugin.

    For commands, it’s recommended to cover the three operations “look up, record, forget”:

    • memory_search: search existing memory by keyword or semantics;
    • memory_add: manually append or confirm a candidate entry;
    • memory_forget: delete or invalidate a specified entry.

    The settings UI should support: browsing entries by type and status, viewing an entry’s provenance chain, manually editing or deleting entries, and adjusting the periodic-summarization time window and token budget. The goal of this design is to turn memory from a “black box” into a “white box.”

    This plugin-based approach also applies to other coding-tool environments with customization capabilities. As long as the host provides a plugin-loading mechanism, a command-registration capability, and config hooks, the same layered approach can be ported over.

    9. Practical Advice and Limitations

    9.1 Four Practical Tips

    1. Start small: first retain only the “constraint” and “preference” types, get the “track → summarize → inject” loop working, then extend to other types.
    2. Control memory size: periodically clean up entries that haven’t been hit for a long time, so the memory bank doesn’t bloat and slow down retrieval or add injection noise.
    3. Protect privacy: memory documents hold a lot of project detail; sensitive information (keys, tokens, internal addresses) should be redacted before writing, and the memory directory shouldn’t be committed to a public repository.
    4. Sample and review periodically: every so often, pull a few entries and trace them back to the raw records to verify accuracy — the most direct measure of memory quality.

    9.2 About the “Initial Release”

    The name “initial release” aptly describes the current state. The author hasn’t systematically studied the language used for plugin development, nor run long-term memory-accumulation tests. This management process was designed mainly from development experience in other languages, then refined through the runtime environment’s high customizability. Therefore:

    • The features are usable and the structure is clear, but there may still be detail defects or missed edge cases;
    • Under scenarios like very long cycles, many parallel projects, and large volumes of similar entries, the merging and conflict-handling strategies still have a lot of room for improvement;
    • It’s more like a “runs, modifiable, open to joint improvement” starting point than a mature final solution.

    If you find problems while using it, you’re welcome to file an issue or contribute code to make the memory process more solid.

    9.3 Conclusion

    Today, as cloud LLMs grow ever more capable, handing “memory” to a local small model may look like a “downgrade,” but it’s actually a rational trade-off between cost and privacy. The four-layer structure guarantees traceability, the local small model takes on high-frequency, lightweight distillation, and periodic summarization plus conflict handling keep memory fresh. Together, these give AI coding assistants the foundation to truly “get to know you better over time.”