Akashic: Closing the Loop Between Code, Conversations, and Team Knowledge
Dewu Technology details their Akashic knowledge engineering system that automatically syncs code changes and AI-assisted development conversations into a three-layer Git-backed knowledge base, using Session and Audit agents to extract reusable insights and CLI tooling to embed the loop into daily workflows.
Introduction
As AI participates more in daily development, team knowledge becomes scattered across code, documents, and development conversations. Code carries implementation details, documents capture architecture and rules, while conversations preserve the trade-offs, boundaries, and experience behind decisions. The team found that manually syncing code changes and conversation conclusions into a knowledge base is unreliable: after code changes, related explanations are often missed; conclusions confirmed during development may stay only in a chat. Switching tasks or teammates still requires re-establishing context and re-verifying boundaries.
To reduce repetitive context-setting and verification, Dewu Technology built the Akashic knowledge engineering practice: first establish a unified knowledge base structure to provide reliable context for AI development tasks; check whether related knowledge needs updating on code changes; after development sessions are archived, extract reusable experience from conversations and write it back to the knowledge base after confirmation. This forms a continuous accumulation loop: the knowledge base supports development tasks, tasks produce code and conversations, and code with conversations drive knowledge base updates, turning paths one person has walked or pitfalls they've hit into reusable experience for the team.
System Architecture
The overall system consists of six modules:
Local Base (Akashic CLI): Developer's local access tool that manages configuration, Skills, and Git Hooks; responsible for scanning, filtering, and uploading Codex and Claude Code development sessions.
Local Development Layer: Developers use AI for solution design, coding, and debugging, reading relevant knowledge base parts per task type, and producing development conversations and code changes.
Engineering Knowledge Layer: Maintains a three-layer knowledge base structure in Git repositories — L1 entry (AGENTS.md), L2 documents and Skills, L3 source code comments — updated via Knowledge Engineering Skills for initialization and continuous code-knowledge write-back, available for team members and their Agents to read on demand.
Session Management Layer: Provides unified session management API, archives raw conversations to OSS to form team data assets, supplying data for knowledge evolution and conversation insights.
Knowledge Evolution Layer: Extracts reusable candidate knowledge from archived sessions; Session Agent extracts, Audit Agent reviews and integrates, finally submitted as MRs for Owner approval before merging.
Conversation Insights Layer: Computes metrics such as session turns, tokens, and time span; combines Agent-extracted topics, summaries, and tags into reports to help teams discover knowledge gaps and recurring development problems, guiding future AI collaboration capability improvements.
Knowledge Base Structure
To enable continuous knowledge accumulation and updates, a knowledge base structure must be designed and a baseline established. The core principle: knowledge is unified in Git repositories, grounded in source code, with the latest knowledge always following the code. Repository knowledge includes global conventions, module rules, and local implementation details, each with different usage frequency, scope, and change rate. Putting everything into AGENTS.md would load excessive irrelevant context per task and increase maintenance cost. Therefore, knowledge is split into three layers by applicability and read timing:
L1 (AGENTS.md): Provides entry point, handles global routing.
L2 (Skills + Repository Markdown): Carries task-reusable knowledge.
L3 (Source Code Comments): Stays close to code evolution, explains constraints in specific implementations.
Agents progressively load knowledge based on task type. For example, when adding a new recall path, the Agent first finds the recall module entry from AGENTS.md, reads module documents to understand how recall results flow downstream; then uses the "Recall Channel Development" Skill to complete integration and verification per conventions; if experiment parameters are involved, additionally reads the Ab-Params topic; when locating specific implementation, checks source code comments for local constraints. Thus, module documents provide background, Skills provide execution methods, and source code with comments provide implementation evidence.
The article includes a concrete L2 directory structure example:
knowledge/
├── README.md # L2 master index
├── docs/
│ ├── 01-positioning.md # Basic positioning
│ ├── 02-architecture.md # Link architecture
│ ├── 03-submodule-index.md # Source navigation
│ ├── 04-concepts.md # Terminology
│ ├── 05-key-dataflows.md # Request and field flows
│ ├── 06-config-extensions.md# Config and extensions
│ ├── 07-dependencies.md # Cross-repo dependencies
│ ├── 08-dev-guide.md # Development and verification
│ ├── modules/ # Module knowledge
│ │ ├── foundation/ # Common basic capabilities
│ │ ├── init/ # Request initialization
│ │ ├── recall/ # Multi-path recall
│ │ ├── merge/ # Candidate fusion & deduplication
│ │ ├── berank/ # Coarse ranking
│ │ ├── aerank/ # Fine ranking
│ │ ├── rerank/ # Re-ranking
│ │ └── ...
│ └── topics/ # Technical topics and business domains
│ ├── ab-params/ # Experiment parameters
│ ├── coldstart/ # Cold start
│ ├── ad-fusion/ # Ad fusion
│ └── ...
└── skills/ # Task-oriented operational procedures
├── recall-channel-dev/ # Recall channel development
│ ├── SKILL.md
│ └── script/ # Accompanying execution scripts
├── metric-anomaly-debug/ # Metric anomaly debugging
│ ├── SKILL.md
│ └── script/
├── feature-field-add/ # Feature field addition
│ ├── SKILL.md
│ └── script/
└── ...Knowledge Base Initialization and Code Update Sync
After defining the structure, the next step is establishing and continuously maintaining the knowledge base. To unify initialization and integrate knowledge updates into daily development flow, the team developed the Akashic-Knowledge Skill covering two processes: first-time repository onboarding to establish a full-repo knowledge baseline, and daily commits that check and update relevant knowledge based on code changes.
First-time Onboarding Initialization: In the repository directory, invoke Akashic-Knowledge Skill. The Agent cross-references existing documents, source code, configs, and test cases to establish L1 knowledge entry, L2 module and topic documents, and necessary L3 source code comments. After confirmation and validation, writes to the repository and records initialization state as the starting point for subsequent incremental sync.
Code Commit Sync: When the Agent prepares to commit code changes, a script locates potentially affected documents based on changed files and knowledge-base mappings, providing diff evidence. The Agent then judges whether module responsibilities, config rules, or implementation boundaries have changed. If updates are needed, generates corresponding knowledge modifications; after confirmation and validation, submits them together with business code. If no update needed, only records the judgment result. This keeps knowledge consistent with code without manual proactive maintenance.
Conversation Knowledge Write-back
Many knowledge pieces do not accompany code modifications but hide in development conversations. The team analyzed their daily development conversations and found extensive manual supplementation and correction: e.g., developers confirming a configuration's effective scope during debugging, or correcting an Agent's understanding of field meanings and effective chains. If these conclusions remain only in historical sessions, subsequent tasks still require re-explanation and re-verification. Therefore, they extract candidate knowledge from OSS-archived team sessions, combine with conversation evidence, cross-check source code and existing knowledge as needed, and after review generate MRs for Owner approval.
The division of labor: models handle knowledge extraction and review, with Agent permissions limited to read, search, and edit; programs handle external system interactions (OSS, MySQL, GitLab), workflow orchestration, and change validation; Owners perform final review. Specific flow:
Extraction and review use the same OSS session snapshot and fixed-version source code and existing knowledge to avoid inconsistent evidence. Each session generates candidate modifications in an independent workspace.
Knowledge deposition completes in two stages: Session Agent reads raw conversations, uses knowledge base routing to view existing knowledge as needed, extracts conclusions with evidence; Audit Agent then checks evidence sufficiency, duplication or conflict with existing knowledge, and finally decides inclusion or exclusion with reasons. If no reliable, reusable conclusion exists, the knowledge base is not modified.
Knowledge gaps discovered from conversations map to different knowledge base levels, with typical correspondences illustrated in the article.
Local Capability Base
The two knowledge write-back loops both rely on members' local capabilities: code changes require invoking the Knowledge Engineering Skill; before extracting knowledge from conversations, development sessions must be archived. If installation, upgrades, and uploads depend on manual execution, issues like inconsistent tool versions, outdated Skills, and forgotten session uploads arise.
Thus they built Akashic CLI to unify tool installation/updates, configuration sync, and session collection. Members continue using existing AI coding tools and Git commit flows; related capabilities run automatically with daily operations.
The onboarding process has three phases:
First Onboarding — Automatic Installation by Agent: The repository's AGENTS.md defines installation check and execution. During daily tasks, the Agent checks the local environment; if CLI is missing, executes a unified install script. The script downloads pre-built binaries, completes config initialization, Skill sync, and Git Hook installation, and triggers first session scan. Members need not separately install CLI, copy Skills, or configure reporting commands.
Daily Development — Background Maintenance Triggered by Git Commit: After Git Commit in onboarded repositories, a Post-Commit Hook launches a background task that checks tool version and config updates, and scans qualifying Claude Code and Codex sessions for upload, without affecting code commits. CLI uses local state records to control duplicate reporting and retry failed uploads: same session successfully uploaded today is not re-reported; recently active sessions can form new snapshots within a default three-day adjustable window for later knowledge extraction; single files retry upload up to three times, then record state for next trigger retry.
Capability Adjustments — Automatic Effect via Unified Distribution: CLI versions, Skills, repository whitelists, and session collection time windows are centrally maintained. After config release, local machines fetch updates on the next daily trigger.
Thus, knowledge engineering capability distribution and session collection integrate into existing development actions, non-intrusive to team members' daily flow, requiring no extra perceived operations.
Conversation Insights
To further mine team experience and problems in AI application from conversations, providing basis for team AI engineering, they built a conversation insights pipeline: archived sessions are statistically analyzed for user turns, duration, tokens, etc., then a read-only Agent summarizes topics and abstracts, and annotates session types and signals like "knowledge supplementation", "direction adjustment", "redo required", "confirmation valid". Reports support filtering by time, repository, and tags; teams can drill from aggregated data to specific sessions to verify context when issues occurred.
Conversation insights reports help identify AI application problems, for example:
Increasing turns with more "knowledge supplementation" signals: possibly business background or module explanations repeatedly added by developers, indicating knowledge base coverage gaps in related paths.
Increasing turns with more "redo required" signals: possibly task understanding, execution path, or result verification issues, requiring drill-down into relevant conversations to judge, and building tools if necessary.
They also help review practice effects: e.g., after introducing knowledge engineering in a repository, as the knowledge loop wrote updates, similar tasks showed effective reduction in turns and correction tags.
Conclusion
Previously, knowledge maintenance often waited until developers finished tasks for manual organization. Code continuously changes, session conclusions and design trade-offs keep emerging, yet knowledge base documents and Skill capabilities struggle to keep up manually. Akashic integrates knowledge base initialization, code change checks, session collection, and candidate knowledge extraction into the development flow, letting content needing maintenance be discovered and updated along with the development process, no longer relying on after-the-fact supplementation.
At the current stage, Agents extract and review candidate content, code and sessions provide verification evidence, and Owners approve before entry. As evidence verification, conflict detection, and change validation improve, they aim to automate updates with sufficient evidence and controllable risk, reserving human judgment for cases with insufficient evidence or involving business trade-offs.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
