sync82

Append a new dated entry to an append-only memory file (progress, decisions, or a custom kind). IMPORTANT: progress and decisions require a "## YYYY-MM-DD" date header somewhere in content. Overwrite-style files (memory, architecture, stack, next_steps, or a custom kind created with write_memory) are rejected — use write_memory for them.

Archive old dated entries from progress.md or decisions.md, keeping only the last N days active (counted in UTC). Entries without a date header are never archived. Archived entries leave the loaded context; to keep what they said, first call with dry_run: true (lists the entries that would be archived, writes nothing), read them with read_memory, then call again with summary: the summary is added as a new active entry in the same step, dated today (UTC) and headed "## YYYY-MM-DD — Summary of N archived entries (from … to …)" unless it has its own "## YYYY-MM-DD" header, which must not be older than the archive cutoff. The project must be given via project or workspace_root, not taken from the last session.

Report which of the six standard memory files exist for a project. A missing current-state file (memory, architecture, stack, next_steps) makes the project unhealthy; progress or decisions with no entry yet only gets a warning. Other warnings point at memory that may be out of date: a current-state file (memory, architecture, stack, next_steps) not updated for stale_days (default 30) while progress or decisions got newer entries, a standard file still empty or holding the blank template, undated progress/decisions entries, and a log with more than 200 active entries. With all_projects: true it checks every project and subproject of the vault instead, one line each, then the details of the ones that are not healthy. Returns an error result (isError: true) when the project (or any project) is unhealthy (a current-state file is missing) — a deliberate signal for the calling agent to act on, not a crash; warnings alone never make it unhealthy.

Create a new project (or subproject of an existing project) in the vault. Safe to call again — an existing project is reported, not duplicated.

Permanently delete a custom memory file. Requires confirm: true — ask the user before calling this with confirm: true. The six standard files (memory, architecture, stack, decisions, progress, next_steps) cannot be deleted this way — use write_memory to clear their content instead. The project must be given via project or workspace_root, not taken from the last session.

Permanently delete a project or subproject from the vault. Requires confirm: true — ask the user before calling this with confirm: true. A top-level project with subprojects also needs subproject_action; with "delete_all", pass expected_subprojects, the number of subprojects you showed the user, and nothing is deleted when the vault holds another number.

Change one entry of an append-only memory file (progress, decisions, or a custom append kind), identified by entry_id — get the ids from read_memory with with_ids: true (add archived: true for an archived entry), or from search_memory with format "json". action "replace" rewrites the entry in place (its position is kept; for progress/decisions content must contain a "## YYYY-MM-DD" header, which also sets the entry's date). action "supersede" appends content as a new entry and adds a "> Superseded by entry N on YYYY-MM-DD." line (today in UTC) to the old one, keeping the history auditable — prefer it when a decision changed rather than was wrong; an archived entry can't be superseded. action "delete" removes the entry permanently and requires confirm: true — ask the user first. The project must be given via project or workspace_root, not taken from the last session.

Export a project's memory to plain Markdown files (one per kind, e.g. memory.md, progress.md) on the local filesystem, for browsing or git-diffing outside an MCP client. output_dir must be absolute (or start with ~/ or HOME/) and may be any directory the server process can write to — it is not confined to the project's own vault or workspace; it is created if missing. Existing files are never replaced unless overwrite is true, and a destination that is a symlink or special file is always refused. A kind with archived entries also gets a <kind>.archived.md file holding them.

Report the current effective vault configuration: active vault path, global config, and (if workspace_root is given) the local .sync82.json config for that workspace.

Import a project's memory from plain Markdown files (one per kind, e.g. memory.md, progress.md) previously produced by export_memory — the inverse operation. Creates the project if it doesn't exist yet. Destructive per kind: an existing kind's content is overwritten, not merged, the same as write_memory; a <kind>.archived.md file restores that kind's archived entries, which are otherwise kept. input_dir must be absolute (or start with ~/ or HOME/) and may be any directory the server process can read — it is not confined to the vault or workspace. Symlinks, special files, files over 10 MB and README.md, CHANGELOG.md, LICENSE.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md are skipped; the files may hold at most 64 MB in total. The import is all or nothing, and the result lists which files create a new kind and which overwrite an existing one; with dry_run: true nothing is written and the result shows what would happen.

Initialize memory files for a project or subproject with structured content. STEP 1 — VAULT SELECTION If the user has not explicitly specified a vault path, call get_vault_config first. If global_vault_configured is true, ask: "A global vault is configured at <global_vault_path>. Do you want to use it? (yes/no)" - Yes → pass that path as "path". No → leave "path" empty. STEP 2 — PROJECT OR SUBPROJECT? IMPORTANT: Before calling this tool, determine whether the target is a top-level project or a subproject. Clues that it IS a subproject: words like "plugin", "module", "package", "extension", "component", "library", "service" in the user's request. When uncertain: ASK the user — "Is this a subproject of an existing project? If yes, which project?" If it is a subproject, set both "project" (the parent) and "subproject" (the component name). If workspace_root is provided: - The tool reads .sync82.json at workspace_root itself (pass search_parent_dirs: true to also look in parent directories, e.g. a monorepo root). - If found with a "subproject" field: re-initializes that subproject. - If found with only "project": re-initializes the root project. - If not found: creates a new .sync82.json at workspace_root. STEP 3 — PROJECT DATA Ask the user: "How do you want to define the project data? 1. Auto-analyze (recommended — I will read the project files) 2. Enter manually" If option 1: set auto_detect: true with workspace_root. If option 2: ask these questions (skip any the user can't answer yet): 1. What does the project do? (description) 2. What is the main goal? 3. What is the current phase? (planning / mvp / active / maintenance) 4. Describe the architecture briefly. 5. What are the main components? (comma-separated) 6. What languages are used? 7. What frameworks and libraries are used? 8. What infrastructure is used? 9. What are the immediate next tasks? Only files that are empty or contain the blank template will be written.

List every memory file (document or entries kind) recorded for a project.

List every project and subproject currently in the vault.

Load a project's memory (every non-blank file) concatenated into one context block, ready to paste into a new session. Overwrite-style files (memory, architecture, stack, next_steps) are always included in full, since they represent current state, not history, and come first. By default (mode "summary") only the 10 most recent dated entries of each log (progress, decisions, custom append kinds) are included and the response is cut at 40 KB; a footer says how many entries were left out. mode "full" includes every entry, cut at 200 KB. "since", "max_entries" and "max_bytes" override these defaults; the response is cut at max_bytes with a note saying so.

Read a memory file's content. For an append-only kind (progress, decisions, or a custom append kind), returns every non-archived entry concatenated in date order. With with_ids: true, each entry is preceded by a "<!-- entry:N -->" line giving the id that edit_entry takes; these lines are never stored if the content is written back. With archived: true, it returns only the entries archive_memory archived instead, so with with_ids: true they can be replaced or deleted with edit_entry. The response is cut at max_bytes (default 1 MB) with a note saying so; load_project_context with since or max_entries reads part of a long log.

Rename a project or subproject in place. Does not update any .sync82.json elsewhere that already points at the old name — those must be re-initialized (init_project_memory) or edited by hand afterward.

Search memory files. By default (match "words") finds the documents and entries holding every word of the query, in any order, ignoring case and accents ("decisao" finds "Decisão"), best matches first; a word ending in "*" matches as a prefix ("instal*"). match "phrase" needs the words in that order; match "exact" finds a literal case-insensitive substring, for paths or identifiers with punctuation. kinds limits the search to some files; since/until to dated entries in a date range. No project given searches the whole vault; project only searches that project and all its subprojects; project+subproject searches just that subproject. Each match is labeled project/file:line, or project/file[YYYY-MM-DD]:line for an entry of a dated log (line counted within that entry).

Save session work to the project memory in a single call. USE THIS TOOL when the user says something vague like: - "update the memory" - "save what we did today" - "record this session" - "update the project notes" FLOW — follow these steps before calling: 1. If the vault context is not already loaded, call load_project_context first to understand what is already recorded and avoid duplicating information. 2. Analyze the current conversation and identify what changed: - Decisions made → "decisions" field - Work completed, features implemented → "progress" field - Updated list of upcoming tasks → "next_steps" field - Changed understanding of the project purpose or status → "memory" field - Architectural changes → "architecture" field - New tools, libraries, or infrastructure added → "stack" field - Custom files (e.g. api, testing) → "custom" field 3. Populate only the fields that actually changed. Leave others unset. PROJECT — pass "project" or "workspace_root" when any field overwrites (next_steps, memory, architecture, stack, or a custom item with mode "write"): a project taken only from the last session is refused for them. Appends alone (progress, decisions, custom "append") may use it. WRITE RULES — how each field is stored: - "progress" → APPENDED to progress (log, never overwrites history) - "decisions" → APPENDED to decisions (log, never overwrites history) - "next_steps" → OVERWRITES next_steps (always reflects current state) - "memory" → OVERWRITES memory (always reflects current state) - "architecture" → OVERWRITES architecture - "stack" → OVERWRITES stack - "custom" → each item uses its own mode ("append" or "write", default "append") FORMAT GUIDANCE: - For appended fields (progress, decisions): the date header "## YYYY-MM-DD" is REQUIRED and enforced. Example: "## 2026-04-23\n- Implemented OAuth2 token validation\n- Files: auth/token.go" Without this header the write will be reject…

Overwrite a memory file's entire content. Destructive: for append-only kinds (progress, decisions, or a custom kind created with append_memory), this replaces every non-archived entry, not just the latest one — use append_memory to add without losing prior entries. Archived entries are kept. The project must be given via project or workspace_root, not taken from the last session.