Synapptic

Type: ../types/agent-memory-system-review.md · Status: current · Tags: trace-derived

Synapptic, from appcuarium's synapptic repository, is a local profile and policy compiler for AI coding assistants. It reads Claude Code JSONL session transcripts, filters and scrubs them, asks an LLM to extract observations across user and agent-failure dimensions, merges those observations into weighted YAML profiles, synthesizes profile/guard prose, and writes that prose into assistant memory surfaces such as Claude Code memory, Cursor rules, Copilot instructions, Codex AGENTS.md, and similar files. The repository also contains a behavioral benchmark for testing each guard's marginal effect and an optional localhost relay/browser sidecar for indexing sessions and token metrics.

Repository: https://github.com/appcuarium/synapptic

Reviewed commit: bcde026770daa5cd9a8ca18ca7182b0aeaa87d1f

Last checked: 2026-05-16

Core Ideas

The raw source layer is Claude Code JSONL, not a general memory database. Synapptic discovers sessions under ~/.claude/projects/*/*.jsonl, derives project slugs from Claude Code project directory names, and treats each transcript file as the source evidence for one extraction run (state.py, cli.py). The raw transcripts remain in Claude Code's filesystem substrate; Synapptic does not import them into its profile store wholesale. They are knowledge artifacts when inspected as evidence, but they have no direct instruction authority until extraction and synthesis produce profile/guard artifacts.

Filtering turns large transcripts into correction-weighted text for extraction. filter_transcript stream-parses JSONL and keeps user text plus assistant text while skipping progress, file-history snapshots, system records, queue operations, tool results, tool-use inputs, and thinking blocks. It boosts turns that contain correction, preference, strong-reaction, or short-reply-after-long-answer signals, then truncates to a token budget by keeping boosted turns plus nearby context first (filter.py, config.py). This filtered trace is an intermediate knowledge artifact: it is evidence selected for profiling, not yet a stable rule.

Scrubbing is part of the extraction boundary. Before transcript text is sent to a provider or persisted as evidence, Synapptic applies three layers of secret redaction: provider-prefix patterns, keyword-value pairs and credential URLs, and high-entropy token detection, with PEM key handling first (scrub.py). This is a system-definition artifact in symbolic/procedural form: it constrains what evidence may cross into LLM extraction and what gets retained as observation evidence.

The extraction schema is a nine-dimension observation model. The default dimensions are expertise, communication, workflow, code_style, expectations, triggers, values, ai_failures, and guards, with profiling modes selecting user-only, agent-only, or both. Global dimensions are inherently user-level, code style stays project-local, and mixed dimensions can later promote across projects (config.py). Extraction loads a configurable prompt pattern, wraps the transcript as reference-only data, optionally includes a high-weight profile summary so the LLM skips already-established patterns, parses JSON observations, validates dimensions, and stamps session/timestamp metadata (extract.py, patterns.py, default prompt).

Profiles are weighted YAML, not append-only lessons. Observations are stored per session as JSON under ~/.synapptic/projects/<project>/observations/, then merged into global/profile.yaml and per-project profile.yaml files with similarity matching, evidence counts, source session ids, weights, per-merge decay, time half-life decay, low-weight pruning, profile versioning, and history snapshots (state.py, profile.py). Mixed dimensions such as expectations, triggers, AI failures, and guards promote to global when similar observations appear across at least two projects. The profile YAML is a derived knowledge artifact while inspected as accumulated evidence; it becomes input to system-definition artifacts during synthesis and output writing.

Synthesis compiles profile facts into instruction-like archetypes and guards. synthesize_archetype filters the weighted profile, treats guards and AI failures as actionable at lower evidence thresholds, asks an LLM to produce exactly User Archetype, Guards, and Known Weaknesses, and saves the markdown archetype under global or project state (synthesize.py). The synthesized guard list is a prose system-definition artifact when written to an assistant's instruction or memory surface: future agents are meant to follow it, not merely cite it.

Output writers target several assistant memory surfaces with per-model guard filtering. Writers emit the synthesized archetype to Claude Code user_archetype.md and update MEMORY.md, Cursor .cursor/rules/synapptic.mdc, Copilot instructions, Gemini styleguide, Codex AGENTS.md, Windsurf, Cline, Aider, and Continue rules. For model-family targets, resolve_target_model looks at stored model_verdicts and filter_for_narrative excludes guards marked backfire or redundant for that model (outputs.py, integrate.py). These rendered files are the highest-authority artifacts in the system because they enter assistant startup context or rule channels.

The benchmark treats guards as testable policies. The benchmark selects guard observations, generates adversarial text-only scenarios, compares WITH and WITHOUT conditions, uses an LLM judge, performs multiple runs with majority vote, adds COMPLY and VIOLATE controls, stores result JSON under ~/.synapptic/benchmarks/, and writes per-model classifications back into matching guard preferences (effective, redundant, backfire, ineffective) (benchmark.py, benchmark_results.py). Benchmark verdicts are evaluation artifacts. They become system-definition inputs when synthesis or output writing suppresses guards for target model families.

Automation exists, but the hook and full pipeline are not identical. synapptic install copies a bundled skill, installs a Claude Code SessionEnd hook, and registers it in ~/.claude/settings.json (cli.py, SessionEnd hook, bundled skill). The full ingest command runs extract, merge, synthesize, and integrate, but the SessionEnd hook runs extract, merge, and project synthesis only; it does not run integrate_archetypes. So the automatic hook updates Synapptic's profile/archetype state, while assistant-facing output files require the full ingest/integrate path or another explicit integration step.

Relay and indexing are a sidecar, not the profile compiler's core store. The optional relay package starts a FastAPI localhost server, forwards Anthropic/OpenAI-compatible traffic, logs token usage and request/response snippets, marks ended sessions, serves browser/dashboard routes, and stores metrics and a session index in ~/.synapptic/relay.db SQLite tables with FTS over titles and first user messages (relay app, store.py, indexer.py, parse.py). This relay SQLite index is a knowledge artifact for browsing and observability. It is not the canonical source of profile observations, guard weights, or assistant policy.

Tests cover the compiler more than the sidecar. The repository has unit tests for transcript filtering, scrubbing, extraction prompts, profile merge/decay/promotion, synthesis filtering, output writers, providers, state, CLI basics, benchmark parsing/scoring/model verdicts, and benchmark result listing, plus a GitHub Actions matrix over Python 3.10-3.12 (tests, tests workflow). I did not find comparable unit coverage for the relay routers, browser UI, or end-to-end hook-to-output freshness.

Comparison with Our System

Dimension	Synapptic	Commonplace
Primary purpose	Learn a personal assistant-facing profile and guard set from Claude Code traces	Build and maintain an agent-operated methodology KB
Raw evidence	Claude Code JSONL transcripts, filtered turns, observation evidence strings	Source snapshots, notes, reviews, work artifacts, validation/review outputs
Canonical derived store	~/.synapptic JSON observations, YAML profiles, archetype markdown, benchmark JSON	Git-tracked markdown collections, schemas, generated indexes, reports
Behavior-changing artifacts	Rendered assistant files, Claude Code memory, Cursor/Copilot/Codex rules, hook/settings config	Instructions, skills, type specs, validators, review gates, authored links
Learning loop	LLM extraction from traces, weighted merge/decay, cross-project promotion, LLM synthesis, benchmark feedback	Human/agent writing, source-grounded review, validation, semantic gates, workshop-to-library promotion
Evaluation	Per-guard WITH/WITHOUT ablation with LLM judge and controls	Deterministic validation plus semantic review workflows
Reviewability	Local files are inspectable, but profile updates are generated and home-directory scoped	Git-native diffs, typed artifacts, replacement archives, explicit collection contracts

Synapptic is closer to a compiler than to a retrieval memory system. The input is a trace corpus; the output is a policy/profile document inserted into future assistant contexts. Commonplace is a library/governance system where durable artifacts are themselves the unit of review. Both systems care about behavior change, but they choose different source-of-truth boundaries: Synapptic's canonical profile lives in user-local YAML and generated assistant files, while commonplace's canonical artifacts live in the repository.

The artifact-authority split is especially clear in Synapptic. Raw JSONL transcripts, filtered turns, observation JSON, relay session rows, and benchmark result JSON are knowledge artifacts when used as evidence. Profile YAML is mostly a derived knowledge artifact, with weights and sources that explain what the system believes about the user. The synthesized archetype, guard list, assistant output files, installed skill, SessionEnd hook, settings registration, scrubber rules, benchmark selection logic, and per-model guard filters are system-definition artifacts because they instruct, configure, route, evaluate, or suppress future behavior.

Compared with commonplace, Synapptic has a stronger automated trace-derived extraction loop and a more direct path from "the model annoyed the user" to "future assistants receive a rule." Commonplace has stronger review and lifecycle controls: source-pinned citations, typed collections, validation, status fields, authored links, and git diffs. Synapptic's profile compiler can adapt quickly, but its generated rules can also become stale, overfit, or incorrectly promoted unless users inspect profiles, benchmark results, and excluded guards.

Synapptic also exposes a useful distinction between profile memory and observability memory. The profile compiler changes future agent behavior. The relay/indexer makes sessions searchable, streams active sessions, and tracks token usage, but it does not by itself change assistant behavior unless its evidence later flows through extraction or manual review.

Read-back: push — compiled archetypes and guard files enter assistant memory, startup, or rule channels for future sessions.

Borrowable Ideas

Treat personal guardrails as compiled artifacts. Commonplace should keep separating evidence notes from instructions, but Synapptic's trace-to-guard pipeline is a good model for workshops where repeated agent failures should become candidate rules. Ready as a workshop pattern; not ready as automatic methodology promotion without review.

Keep raw traces, filtered traces, and distilled rules separate. Synapptic's layers are useful even where its exact home-directory substrate is not. Commonplace trace workflows should preserve the raw source, filtered working view, extracted observations, weighted or reviewed candidates, and final instruction artifacts as separate lineage stages.

Use per-rule ablation before granting broad authority. The WITH/WITHOUT benchmark is noisy because it depends on generated scenarios and LLM judges, but the design asks the right question: did this rule change model behavior beyond baseline? Commonplace semantic review could borrow the ablation framing for high-impact instructions.

Make target-model filtering explicit. Synapptic records model-specific guard verdicts and uses them to omit redundant or harmful guards from particular output targets. Commonplace usually writes model-neutral instructions, but if we generate runtime context packs for different agents, model-specific suppression should be a named policy instead of an ad hoc edit.

Do not borrow home-directory state as the only source of truth for methodology. Synapptic's ~/.synapptic design is appropriate for personal profiles. Commonplace needs git-native lineage, review status, and replacement history for shared methodology artifacts.

Trace-derived learning placement

Trace source. Synapptic qualifies as trace-derived learning. The qualifying traces are Claude Code session JSONL files under ~/.claude/projects/*/*.jsonl; the optional relay can also persist request logs and index session metadata, but the implemented profile extraction path reads Claude Code transcripts.

Extraction. Extraction is staged. A deterministic filter strips non-conversation records and tool payloads, boosts likely correction/preference turns, truncates to budget, and scrubs secrets. An LLM extraction prompt then produces JSON observations across the active dimensions. Existing high-weight profile entries can be included so the extractor focuses on novel signal rather than re-extracting established patterns.

Storage substrate. Raw transcripts stay in Claude Code project directories. Filtered traces are transient text passed to the LLM. Extracted observations persist as JSON under ~/.synapptic/global/observations/ or ~/.synapptic/projects/<project>/observations/, with project metadata. Weighted profiles persist as YAML under ~/.synapptic/global/profile.yaml and per-project profile.yaml, with history snapshots under ~/.synapptic/profile_history/. Synthesized archetypes persist as markdown under the same global/project state. Rendered assistant files persist in each target assistant's own filesystem surface. Benchmark verdicts persist as JSON under ~/.synapptic/benchmarks/ and as model_verdicts fields inside profile preferences. The relay sidecar persists metrics, session index rows, FTS rows, and ended-session markers in ~/.synapptic/relay.db.

Representational form. Raw transcripts and filtered turns are prose/conversation traces wrapped in JSONL structure. Observation JSON and profile YAML are mixed prose plus symbolic metadata: dimensions, confidence, evidence, weights, evidence counts, sources, projects, timestamps, exclusions, and model verdicts. The synthesized archetype and rendered assistant files are prose system-definition artifacts. Scrub rules, dimension routing, merge thresholds, decay constants, promotion criteria, benchmark classifiers, output target mappings, and SQLite schemas are symbolic system-definition artifacts. There is no learned distributed-parametric state in the repository; LLM providers are used as external oracles.

Lineage. Lineage is moderate. Observation files keep session_id, project_slug, timestamps, and evidence snippets; profile preferences keep source session ids and project lists capped to recent sources; profile history snapshots allow rollback and diff. The system does not retain full source offsets, extraction prompt/model/version per observation, or a deterministic regeneration record for every synthesized guard. Benchmark caches include seed/model/guard hashes, and benchmark results record provider/model/judge/temperature/runs, which gives better lineage for guard evaluation than for initial extraction.

Behavioral authority. Raw transcripts, filtered turns, observation JSON, profile YAML, benchmark result JSON, and relay index rows are knowledge artifacts when consumed as evidence, explanation, or audit input. The extraction prompt, active pattern, scrubber, dimension routing, merge/decay/promote rules, synthesis prompt, target-model filter, output writers, installed skill, SessionEnd hook, Claude settings entry, and rendered assistant files are system-definition artifacts. The strongest behavioral authority is the assistant memory/rules output, because it is loaded by future agents before or during work.

Scope. Scope is personal and project-aware. Communication, workflow, values, and expertise are global; code style is project-local; expectations, triggers, AI failures, and guards start local and can promote globally when seen across multiple projects.

Timing. Extraction can run manually through extract, merge, and synthesize, while output writing is reached through the all-in-one ingest path or the internal integrate_archetypes function. SessionEnd processing is online at session close but backgrounded and detached. Benchmarking is offline and explicit; its verdicts affect later synthesis/output filtering after results are recorded and profiles are regenerated.

Survey placement. On the trace-derived learning survey, Synapptic belongs in the trace-to-profile and trace-to-policy family. It strengthens the survey claim that behavior-changing memory often appears after a distillation boundary: raw transcripts are evidence, but the durable behavior change is carried by weighted profiles, synthesized guards, assistant memory files, and benchmark-informed model filters.

Curiosity Pass

The most important artifact is not the profile YAML; it is the rendered assistant file. The profile explains what Synapptic believes, but behavior changes only when integrate_archetypes writes the archetype into a target assistant surface that future sessions actually load.

The SessionEnd hook is narrower than the marketing path. It extracts, merges, and synthesizes for the closed session's project, but does not call integration. That makes the profile fresher than the assistant-facing files unless another command writes outputs.

The benchmark is unusually concrete for a memory tool. It does not merely count extracted memories. It asks whether a specific guard improves behavior against an adversarial scenario. The weak point is oracle quality: the scenario generator, respondent, and judge are all LLM-mediated, so controls and separate judges are useful but not a full proof.

The relay sidecar could be mistaken for the memory system. It stores searchable session metadata and request metrics in SQLite, which is useful for observability, but it is not the source of truth for profile learning. The compiler path still runs through transcript filtering, extraction, profile merge, synthesis, and output writing.

There are implementation rough edges worth tracking. In the inspected commit, integrate_archetypes returns five values per update, while the ingest loop unpacks three. If exercised, that mismatch would affect the full pipeline's final integration reporting or execution path (integrate.py, cli.py). That does not undermine the architecture, but it matters for whether generated archetypes reliably reach target memory files.

What to Watch

• Whether the SessionEnd hook starts running integration or whether automatic processing remains profile-only until a manual command writes outputs.
• Whether observation lineage gains source offsets, extraction prompt/model versions, and regeneration metadata.
• Whether benchmark verdicts become a required promotion gate for guards before they enter high-authority assistant files.
• Whether relay/indexer data becomes part of extraction, or remains a browsing and metrics sidecar.
• Whether tests add end-to-end coverage for install, hook, ingest-to-output integration, relay routers, and browser session parsing.
• Whether support for non-Claude transcript sources is implemented with the same artifact split and privacy boundary.

Bottom Line

Synapptic is a genuine trace-derived profile and policy compiler. Its behavior-changing memory is not the raw session transcript or the relay index; it is the pipeline from filtered/scrubbed Claude Code traces to extracted observations, weighted profile YAML, synthesized guards, benchmark verdicts, and assistant-specific memory files. Commonplace should borrow its separation of trace evidence from compiled policy, its per-guard ablation framing, and its model-specific guard filtering idea, while keeping stronger git-native review, lineage, validation, and promotion controls before trace-derived rules gain lasting methodology authority.

Relevant Notes:

• Trace-derived learning techniques in related systems - extends: Synapptic turns Claude Code session traces into weighted profiles, guards, output memory files, and benchmark-informed model filters.
• Axes of artifact analysis - exemplifies: Synapptic requires separating transcripts, filtered traces, observations, profile YAML, rendered assistant files, benchmark verdicts, relay SQLite rows, prompts, config, and hooks by substrate, form, lineage, and authority.
• Knowledge artifact - distinguishes: raw transcripts, filtered traces, observations, profile YAML, benchmark JSON, and relay indexes mostly serve as evidence or context.
• System-definition artifact - distinguishes: synthesis prompts, scrub rules, merge/promotion policies, output writers, hooks, settings, and rendered assistant files instruct, configure, evaluate, or route future behavior.
• Use trace-derived extraction - exemplifies: Synapptic extracts durable observations and candidate rules from session transcripts rather than relying on manually authored memory alone.
• Knowledge storage does not imply contextual activation - contrasts: Synapptic changes behavior only when generated archetypes reach assistant startup or rule surfaces, not merely when observations are stored.